Skip to content

Structured YouTube data: send queries. Cursor-paginated, 2 credits per successful call.

GET · POST2 credits / successful callCursor-paginated
GEThttps://api.scrapier.io/api/v2/youtube-search-full/Open in Playground

Call GET /api/v2/youtube-search-full/ with queries. The results are in data.items; send data.next_cursor back as cursor to get the next page. 18 optional parameters refine the call (see Parameters).

Terminal window
curl -G "https://api.scrapier.io/api/v2/youtube-search-full/" \
-H "X-API-Key: YOUR_API_KEY" \
--data-urlencode "queries=fitness" \
--max-time 210
NameTypeRequiredDefaultDescription
X-API-Key headerstringyes—Your API key from the dashboard.
queriesstringyese.g. fitnessSearch term. Required on first call; ignored when cursor is supplied.
cursorstringno—Pagination cursor returned in the previous response's next_cursor. Pass it back unchanged to fetch the next page. When next_cursor is null, you have reached the last page.
max_results_videointegerno20Max regular videos returned per page (0 = exclude). One page = one native YouTube search page (~20 videos). Locked into the cursor.
max_results_shortsintegerno10Max shorts returned per page (0 = exclude; videos=0 + shorts>0 switches to YouTube's Shorts-only search). Locked into the cursor.
max_results_streamsintegerno0Max currently-live streams per page (0 = exclude). Locked into the cursor.
sort_bystringnorelevanceSort order: relevance | upload_date | view_count | rating (applied server-side by YouTube)
upload_datestringno—Upload-date filter: hour | today | week | month | year (empty = any time)
durationstringno—Duration filter: short (<4 min) | medium (4-20 min) | long (>20 min) (empty = any)
countrystringnoUSResult region (2-letter country code, YouTube gl)
languagestringnoenInterface language for result texts (YouTube hl, e.g. en, es, de)
download_subtitlesbooleannofalseFetch the transcript + caption language list for each video (true/false). Best-effort within the per-call time budget; rows always carry details first
subtitles_languagestringnoenPreferred transcript language code (e.g. "en", "es", "fr"); falls back to an auto-translation or the original track
subtitles_formatstringnosrtTranscript format: srt | text | timestamp (JSON list of {start, duration, text})
fetch_metadatabooleannotrueEnrich each video with exact likes, full description, tags, category, publish date, subscribers and comment count (true/false)
fetch_shorts_statsbooleannofalseFetch subscribers + comment count for shorts too (default false: skips an extra ~22KB upstream request per short; set true to include them; videos always get them when fetch_metadata is true)
isHDbooleannofalseFilter: HD only (server-side YouTube filter)
is4KbooleannofalseFilter: 4K only (server-side YouTube filter)
isLivebooleannofalseFilter: live streams only (server-side; enables streams automatically)
hasSubtitlesbooleannofalseFilter: videos with subtitles/CC only (server-side YouTube filter)
Advanced
NameTypeDefaultDescription
use_proxybooleantrueRoute the request through Scrapier's residential proxy pool. Default: true. Leave as is unless support tells you otherwise.
raw_databooleanfalseWhen true, the response carries the full raw upstream payload(s) the scraper received (GraphQL / JSON API bodies, HTML, embedded JSON-LD -- exactly as the platform returned them) under raw_responses, in place of the formatted items. When false (default) you get the formatted output. Pagination (cursor / next_cursor) works the same in both modes.
{
"success": true,
"data": {
"queries": "fitness",
"page": 1,
"page_size": 1,
"items": [
{
"title": "30-minute fitness workout",
"translatedTitle": null,
"type": "video",
"id": "dQw4w9WgXcQ",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hq720.jpg",
"viewCount": 1240000,
"date": "2026-11-10T08:00:00.000Z",
"likes": 38018,
"location": null,
"channelName": "Example Fitness",
"channelUrl": "https://www.youtube.com/@examplefitness",
"channelUsername": "examplefitness",
"collaborators": null,
"channelId": "UCuudpdbKmQWq2PPzYgVCWlA",
"numberOfSubscribers": 367000,
"duration": "00:30:20",
"commentsCount": 968,
"text": "Full 30-minute session, no equipment needed. #fitness",
"translatedText": null,
"descriptionLinks": [
{
"url": "https://www.youtube.com/hashtag/fitness",
"text": "#fitness"
}
],
"subtitles": [
"en"
],
"transcript": "1\n00:00:00,240 --> 00:00:03,840\nWelcome to today's workout\n",
"transcriptLanguage": "en",
"transcriptFormat": "srt",
"order": 1,
"commentsTurnedOff": false,
"fromYTUrl": "https://www.youtube.com/results?search_query=fitness",
"isMonetized": null,
"hashtags": [
"#fitness"
],
"isLive": false,
"isLiveContent": false,
"isFamilySafe": true,
"tags": [
"workout",
"home workout"
],
"videoCategory": "Sports",
"details_fetched": true,
"keyword": "fitness",
"scraped_at": "2026-12-01T12:00:00.000Z",
"video_id": "dQw4w9WgXcQ",
"category": "video",
"channel_name": "Example Fitness",
"view_count": 1240000,
"duration_seconds": 1820,
"published_at": "2026-11-10T08:00:00.000Z",
"input_query": "fitness"
}
],
"next_cursor": "eNo1jt1qwzAMhd9F11k3SNlF7_YAexEhjOXETvwT2VaSjb77lMHgcD7O0eHA_QWeoxYxH8Twnf..."
}
}

Sample from the live catalog; arrays trimmed to 3 items. Results are in data.items.

FieldTypeExampleDescription
queriesstringfitness—
pageinteger1—
page_sizeinteger1—
itemsarray[1 item]The results.
next_cursorstringeNo1jt1qwzAMhd9F11k3SNlF7_YAexEhjOXETvwT2VaSj…Pass back as cursor for the next page. null on the last page.
items[].titlestring30-minute fitness workout—
items[].translatedTitlenullnull—
items[].typestringvideo—
items[].idstringdQw4w9WgXcQ—
items[].urlstringhttps://www.youtube.com/watch?v=dQw4w9WgXcQ—
items[].thumbnailUrlstringhttps://i.ytimg.com/vi/dQw4w9WgXcQ/hq720.jpg—
items[].viewCountinteger1240000—
items[].datestring2026-11-10T08:00:00.000Z—
items[].likesinteger38018—
items[].locationnullnull—
items[].channelNamestringExample Fitness—
items[].channelUrlstringhttps://www.youtube.com/@examplefitness—
items[].channelUsernamestringexamplefitness—
items[].collaboratorsnullnull—
items[].channelIdstringUCuudpdbKmQWq2PPzYgVCWlA—
items[].numberOfSubscribersinteger367000—
items[].durationstring00:30:20—
items[].commentsCountinteger968—
items[].textstringFull 30-minute session, no equipment needed. …—
items[].translatedTextnullnull—
items[].descriptionLinksarray[1 item]—
items[].subtitlesarray[1 item]—
items[].transcriptstring1 00:00:00,240 --> 00:00:03,840 Welcome to to…—
items[].transcriptLanguagestringen—
items[].transcriptFormatstringsrt—
items[].orderinteger1—
items[].commentsTurnedOffbooleanfalse—
items[].fromYTUrlstringhttps://www.youtube.com/results?search_query=…—
items[].isMonetizednullnull—
items[].hashtagsarray[1 item]—
items[].isLivebooleanfalse—
items[].isLiveContentbooleanfalse—
items[].isFamilySafebooleantrue—
items[].tagsarray[2 items]—
items[].videoCategorystringSports—
items[].details_fetchedbooleantrue—
items[].keywordstringfitness—
items[].scraped_atstring2026-12-01T12:00:00.000Z—
items[].video_idstringdQw4w9WgXcQ—
items[].categorystringvideo—
items[].channel_namestringExample Fitness—
items[].view_countinteger1240000—
items[].duration_secondsinteger1820—
items[].published_atstring2026-11-10T08:00:00.000Z—
items[].input_querystringfitness—

Pass data.next_cursor back as cursor until it is null. Required inputs are ignored once a cursor is sent. Each page is one billed call. More in Pagination.

const url = "https://api.scrapier.io/api/v2/youtube-search-full/";
let params = { queries: "fitness" };
const items = [];
for (let page = 0; page < 10; page++) { // each page is one billed call
const res = await fetch(`${url}?${new URLSearchParams(params)}`, {
headers: { "X-API-Key": "YOUR_API_KEY" },
signal: AbortSignal.timeout(210_000),
});
const body = await res.json();
if (!res.ok) throw new Error(body.error ?? body.detail ?? `HTTP ${res.status}`);
const data = body.data;
items.push(...(data.items ?? []));
if (!data.next_cursor) break; // null = last page
params = { cursor: data.next_cursor };
}

Failed calls are free. Branch on the HTTP status and read the message from error (or detail). Full details in Errors.

StatusMeaningRetry?Charged?
400Bad or missing input.No — fix the paramsNo
401 / 403Missing, invalid or revoked API key.No — fix the keyNo
402Out of credits (body has balance).No — top upNo
404Unknown endpoint slug.No — check the slugNo
429 / 503Busy or throttled.Yes — after Retry-AfterNo
5xxTarget site or upstream failure, or timeout.Yes — with backoffNo
  • Nothing special: send the inputs, read the result.