YouTube

Search YouTube

Search YouTube videos, channels, playlists, Shorts, shelves and live streams, with continuation. Filter by upload date or publication time, sort, type, duration and region. Set includeExtras=true for expanded video records. Each successful request costs 1 account credit, including partial results. Failed requests cost 0 credits.

get/v1/youtube/search

Request

  • Base URL: https://api.scrapeatlas.com
  • URL: https://api.scrapeatlas.com/v1/youtube/search
  • Auth: API key in header x-api-key

Query parameters

querystring required

Search text (1–500 characters). YouTube's intitle: operator narrows title matches.

uploadDate'last_hour' | 'today' | 'this_week' | 'this_month' | 'this_year'

last_hour, today, this_week, this_month or this_year (rolling windows).

sortBy'relevance' | 'popular'

relevance (default) or popular (view count).

type'videos' | 'shorts' | 'channels' | 'playlists'

videos, shorts, channels or playlists. Default: mixed results.

duration'under_3_min' | 'between_3_and_20_min' | 'over_20_min'

under_3_min, between_3_and_20_min or over_20_min (videos only; implies type=videos).

regionstring

Two-letter region code selecting YouTube's regional results (default US).

continuationTokenstring

YouTube's own continuation token for the next page, or null at the end. Pass it back unchanged as continuationToken; tokens are caller-carried and never stored.

includeExtras'true' | 'false'

Set to true to read per-video details for every listed video and Short (two small public API calls per video, issued together: the player metadata and the watch-next data; up to 48 videos, 12 at a time) and add description, commentCountText, commentCountInt, likeCountInt, likeCountText, publishDate (ISO 8601 with the channel's offset), genre, durationMs and durationFormatted to each video, and replace viewCountText/viewCountInt with the exact count. Defaults to false. Videos whose details could not be read keep null extras and the response is partial with extras_incomplete.

extrasDetail'full' | 'player'

full (default) reads the player and the watch-next data per video; player reads only the player (one call per video, about half the upstream bytes) and leaves the watch-next fields commentCountText and commentCountInt null (description is then the player's raw text), with the coverage warning watch_next_omitted. Requires includeExtras=true.

number
OR
string

Earliest publication time to include, ISO 8601 or Unix seconds. Applied through the narrowest covering uploadDate and checked on each dated item. Works with type=shorts.

number
OR
string

Publication time to stop before, ISO 8601 or Unix seconds; later than since. Not available with type=shorts.

Response

Inspect the response status and failure or coverage fields.

OR

Changes

No recorded changes to this operation across all 1 revision of this API.