# 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. Send `include=channel` to add each result's channel subscriber count (`post.ext.author_followers`) in the same call (1 credit per distinct channel, at most 5 per page); the two combine. 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 for the search page. `includeExtras=true` adds a flat 5 credits for the single hydration call that fills view, like and comment counts and `duration_seconds` on the whole page. The increment never repeats: the page caps at 50 results, which one hydration call covers, so a hydrated page of 50 costs 6 credits and so does a hydrated page of 5. include=channel adds 1 credit per distinct channel filled, at most 5 per page, with channels that could not be read refunded, so a page with both is at most 11 With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total. With `seen`, a page's price falls with its share of rows you already received under that id; credits for joined data (`include=`) are never discounted. 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. |
| `include` | no | Set to `channel` (one token only) to add each row's channel stats in this one call. `channel` puts the channel's subscriber count on `post.ext.author_followers` (YouTube's own figure, which it rounds to three significant figures above 1,000) and fills the channel's `post.author.display_name`, `.avatar_url` and `.username` where missing. It also adds the country the channel's owner set, as an ISO 3166-1 alpha-2 code on `post.ext.author_country` (null when the channel sets none). Each join costs 1 credit per distinct video or channel it filled, and never more than 5 per 50; ids that could not be filled are refunded. Each join adds 0.2 to 0.7 seconds on a fresh page (one lookup per 50 ids, never more than 8 seconds). Read `data.hydration` for the rows, lookups, credits held and kept, and the time. (channel) |
| `exact_dates` | no | Free views, likes, comments and channel handle are on by default and cost no credit: every result is joined to one per-video lookup (`post.engagement.views` / `.likes` / `.comments`, `post.content.duration_seconds`) and one per-channel lookup (`post.author.username`, `.display_name`, `.avatar_url`), a page at a time, adding about 0.2 to 0.7 seconds each (never more than 3). Dates are exact on this endpoint either way. Set to `false` to skip both lookups and get the snippet-only rows. A row a lookup could not fill keeps its nulls, and `_warnings` carries `stats_partial` or `stats_unavailable` (counts) and `handle_partial` or `handle_unavailable` (handle). The subscriber count stays `include=channel`. (true \| false) |
| `since` | no | Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off the page, and the page that reaches one ends the walk: `next_cursor` is not returned and `pagination.stopped_at` is `since`. Sending it sets the newest-first sort shown in this endpoint's sort parameter (any other sort value is a free 400). The page still costs what a page costs, so you pay for the pages you walk and no more. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`. |
| `until` | no | Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`. |
| `min_views` | no | Keep only rows with at least this many views (`post.engagement.views`). A row whose view count is unknown is discarded, so every returned row meets the floor. Filtering runs on our side after each page is fetched, so every page walked is billed as usual; `data.walk.discarded` counts what was removed and why. Each page is its own entry in `GET /v1/credits/transactions`, under the page's request id listed in `data.walk.request_ids`. |
| `max_age_days` | no | Keep only rows published within this many days (`post.published_at`), 1 to 3650. A row with no date is discarded. Filtering runs on our side after each page is fetched, so every page walked is billed as usual; `data.walk.discarded` counts what was removed and why. Each page is its own entry in `GET /v1/credits/transactions`, under the page's request id listed in `data.walk.request_ids`. |
| `sort_rows` | no | `views`: return the kept rows ordered by view count, highest first, across every page walked. Rows without a view count go last. (views) |
| `max_pages` | no | 1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them (after any filter). Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped. |
| `max_items` | no | 1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows (after any filter), then stop with `data.walk.stopped: "max_items"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`"time_budget"`): send the returned cursor with the same params to continue. |
| `max_credits` | no | 1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: "max_credits"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price. |
| `seen` | no | An id you choose (1 to 64 letters, digits, `.`, `_` or `-`). Rows your account already received under the same `seen` id are removed from the page, and the page price falls with the share of repeats: page credits x new rows / rows on the page, rounded up, so a page of nothing but repeats is free. Only the page's own price is discounted: credits for joined data (`include=`) are charged only for rows you have not received, and are never discounted. The memory lasts 24 hours from the last call that used the id, holds row ids only, and is private to your account. Use one id across a set of related searches; `data.walk.repeats` counts what was removed. |

## Code example

```bash
curl -G "https://www.socialcrawl.dev/v1/youtube/search/advanced" \
  --data-urlencode "query=lofi hip hop" \
  -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. includeExtras=true adds view, like and comment counts and the duration; include=channel adds each channel's subscriber count.

### 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 costs 1 to 11 credits per request: the page price, a flat add-on for includeExtras=true, and another for include=channel, 10 credits on top if you use both. 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