# YouTube Search Advanced API (https://www.socialcrawl.dev/platforms/youtube/search-advanced)

> Searches YouTube videos with the full filter set — sort `order`, `duration`, live/upcoming `event_type`, Creative-Commons `license`, `category`, `region`, `language`, and `published_after`/`published_before` date windows — returning video id, title, thumbnail, channel, and publish time, plus a `cursor` for the next page. Results are always videos. This is the reliable lane for date-window, sort, and page-size work. `published_after`/`published_before` take exact RFC-3339 bounds and are genuinely applied (`/v1/youtube/search`'s coarse `uploadDate` buckets are silently dropped by that upstream whenever a `type` is also set); `order=date` is an exact sort (measured: zero inversions); `order=viewCount` is YouTube's popularity-weighted ranking — strongly view-correlated with the top result leading, but not strictly descending, so with `includeExtras=true` sort the page client-side on `engagement.views` for exact ranking (the counts are in the response); and `max_results` returns up to the page size you ask for, 1–50 (exact when YouTube has the supply). Every result carries an exact per-second `published_at`. Set `includeExtras=true` to add view/like/comment counts and `duration_seconds` to every result (+5 credits per page) — without it those are null, because YouTube's search index returns snippets only. SHORTS: there is no `type=shorts` here and there cannot be — YouTube's Data API has no Shorts concept, so no filter can distinguish a vertical Short from any other video. The documented APPROXIMATION is `duration=short` (under 4 minutes) plus `includeExtras=true` and a client-side filter on `post.content.duration_seconds <= 180`; it will include short landscape videos, so treat it as a narrowing heuristic, not a Shorts filter. For a real Shorts shelf use `/v1/youtube/search?type=shorts`, which reads YouTube's own Shorts surface and carries its own caveats.

TL;DR: `GET /v1/youtube/search/advanced` costs 1 credit per call and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Search query. |
| `order` | no | Sort order: date, rating, relevance (default), title, videoCount, viewCount. `order=date` is exact (measured: zero inversions against the timestamps). `order=viewCount` is YouTube's popularity-weighted ranking — the top result is the true maximum but mid-list order is approximate, so for exact ranking add `includeExtras=true` and sort the page on `engagement.views` client-side. Both are far more faithful than `/v1/youtube/search`'s `sortBy=popular`, which is not view-ordered at all. |
| `duration` | no | Video length: short (<4m), medium (4–20m), long (>20m), any. Genuinely applied (unlike `/v1/youtube/search`'s `duration`, which the upstream ignores). `short` plus a client-side `post.content.duration_seconds <= 180` filter is the documented Shorts approximation — see the endpoint description for why it is an approximation and not a Shorts filter. |
| `event_type` | no | Broadcast type: live, upcoming, completed. |
| `license` | no | License filter: creativeCommon, youtube, any. |
| `category` | no | YouTube video category id (e.g. 10 = Music). |
| `region` | no | ISO 3166-1 alpha-2 country code. |
| `language` | no | Preferred result language (ISO 639-1). |
| `published_after` | no | RFC-3339 datetime lower bound (e.g. 2026-01-01T00:00:00Z). Exact and genuinely applied — this is the endpoint to use for date-window work. |
| `published_before` | no | RFC-3339 datetime upper bound. Exact and genuinely applied. |
| `channel_id` | no | Restrict results to a single channel id. |
| `max_results` | no | Maximum number of videos to return (1–50). Honored exactly — a page of 50 returns 50 (live-verified). |
| `cursor` | no | Pagination cursor from a previous response — fetches the next page. |
| `safe_search` | no | Safe-search filter: none, moderate, strict. |
| `video_caption` | no | Caption filter: any, closedCaption, none. |
| `video_definition` | no | Quality filter: any, high, standard. |
| `video_dimension` | no | Dimension filter: 2d, 3d, any. |
| `video_embeddable` | no | Restrict to embeddable videos: true, any. |
| `video_type` | no | Type filter: any, episode, movie. |
| `topic_id` | no | Restrict to a Freebase topic id (e.g. /m/04rlf for music). |
| `location` | no | Latitude,longitude center for a geo search (e.g. 37.42307,-122.08427). Must be used together with location_radius. |
| `location_radius` | no | Radius around location with a unit suffix (e.g. 50km, 10mi). Must be used together with location. |
| `includeExtras` | no | Set to `true` to add the view, like and comment counts (`post.engagement.views` / `.likes` / `.comments`) and the video length (`post.content.duration_seconds`) to every result. Left off, those four are null — YouTube's search index returns snippets only, so the counts come from a second lookup. Costs +5 credits per page (a page is at most 50 results, so it is a flat +5, not per result) and adds one upstream round-trip. If that lookup fails the page still returns, un-hydrated, with the +5 refunded and `_warnings: ["extras_unavailable"]` on the response. |

## Code example

```bash
curl "https://www.socialcrawl.dev/v1/youtube/search/advanced?query=lofi%20hip%20hop" \
  -H "x-api-key: sc_YOUR_API_KEY"
```

## FAQ

### How do I run an advanced YouTube video search?

Send a GET to /v1/youtube/search/advanced with a query plus any filters. Results are always videos, returned with video ID, title, thumbnail, channel, and publish time.

### What filters does advanced search support?

Sort order, duration (short, medium, long), event_type (live, upcoming, completed), license, category, region, language, and published_after / published_before date windows.

### How do I find videos published in a date range?

Pass published_after and published_before as RFC-3339 datetimes, for example 2026-01-01T00:00:00Z, to bound results to that window.

### How is this different from the basic search endpoint?

The basic /v1/youtube/search endpoint keeps things simple; search/advanced exposes the full YouTube filter set for precise, video-only queries.

### How much does advanced search cost?

It is a standard endpoint at 1 credit per request. New accounts get 100 free credits and there is no daily quota.

See the full YouTube API: https://www.socialcrawl.dev/platforms/youtube

## Pricing

- Standard endpoints: 1 credit per call
- Advanced endpoints: 5 credits per call
- Premium endpoints: 10 credits per call
- 100 free credits on signup, no credit card required. Cached responses cost 0 credits. Credit packs never expire.
- Full pricing: https://www.socialcrawl.dev/pricing

## Explore with AI

Questions this API answers, phrased for an AI assistant:

- How to search YouTube videos with date and duration filters via API
- YouTube advanced search API without Data API quota