Skip to content

Structured YouTube data: send country_code. Cursor-paginated, 1 credit per successful call.

GET · POST1 credit / successful callCursor-paginated
GEThttps://api.scrapier.io/api/v2/youtube-trending/Open in Playground

Call GET /api/v2/youtube-trending/ with country_code. The results are in data.videos; send data.next_cursor back as cursor to get the next page. 2 optional parameters refine the call (see Parameters).

Terminal window
curl -G "https://api.scrapier.io/api/v2/youtube-trending/" \
-H "X-API-Key: YOUR_API_KEY" \
--data-urlencode "country_code=US" \
--max-time 210
NameTypeRequiredDefaultDescription
X-API-Key headerstringyes—Your API key from the dashboard.
country_codestringyese.g. USTwo-letter ISO country code (e.g., US, BD, IN, GB). 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.
content_typestringnomusicTrending list: music (trending music videos, 30; regions without that chart fall back to daily top music videos) | movies (trending trailers, 30) | top_music_videos (100) | gaming | sports | news | live | learning | fashion. Invalid value -> 400. Locked into the cursor.
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": {
"country_code": "US",
"content_type": "music",
"page": 1,
"page_size": 25,
"videos": [
{
"type": "video",
"id": "V-uIp-WuD60",
"video_id": "V-uIp-WuD60",
"title": "Patient Zero",
"status": "OK",
"url": "https://www.youtube.com/watch?v=V-uIp-WuD60",
"description": "Provided to YouTube by Universal Music Group\n\nPatient Zero · Taylor Swift\n\nThe Life of a Showgirl: The Encore\n\n℗ 2026 Taylor Swift\n\nReleased on: 2026-09-25\n\nCom",
"duration": 226,
"views": "6722880",
"view_count": 6722880,
"likes": "95077",
"like_count": 95077,
"comments": null,
"channel": {
"id": "UCPC0L1d253x-KuMNwa05TpA",
"name": "Taylor Swift - Topic",
"handle": null,
"url": "https://www.youtube.com/channel/UCPC0L1d253x-KuMNwa05TpA",
"subscriber_count": null,
"thumbnails": [],
"badges": []
},
"channel_id": "UCPC0L1d253x-KuMNwa05TpA",
"channel_name": "Taylor Swift - Topic",
"keywords": [
"Taylor Swift",
"テイラースウィフト",
"テイラー・スウィフト"
],
"is_ratings_allowed": true,
"is_live": false,
"is_live_content": false,
"is_family_safe": true,
"category": "Music",
"is_private": false,
"is_exclusive": false,
"thumbnails": [
{
"url": "https://i.ytimg.com/vi/V-uIp-WuD60/maxresdefault.jpg",
"width": 1920,
"height": 1080
}
],
"embed_url": "https://www.youtube.com/embed/V-uIp-WuD60",
"is_embeddable": true,
"is_unlisted": false,
"publish_date": "2026-09-24T21:02:10-07:00",
"published_at": "2026-09-24T21:02:10-07:00",
"relative_date": null,
"upload_date": "2026-09-24T21:02:10-07:00",
"trending_position": 1,
"previous_position": null,
"periods_on_chart": null,
"chart_view_count": null,
"artists": [
"Taylor Swift"
],
"release_date": "2026-09-24",
"country_code": "US",
"content_type": "music",
"source": "youtube_charts",
"chart_type": "TRENDING_VIDEOS",
"enriched": true,
"scraped_at": "2026-10-03T04:28:40.122Z"
}
],
"next_cursor": "eyJjdCI6Im11c2ljIiwiaSI6IlVTIiwicCI6Miwic24iOlsiMGExYjJjIl19"
}
}

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

FieldTypeExampleDescription
country_codestringUS—
content_typestringmusic—
pageinteger1—
page_sizeinteger25—
videosarray[1 item]The results.
next_cursorstringeyJjdCI6Im11c2ljIiwiaSI6IlVTIiwicCI6Miwic24iO…Pass back as cursor for the next page. null on the last page.
videos[].typestringvideo—
videos[].idstringV-uIp-WuD60—
videos[].video_idstringV-uIp-WuD60—
videos[].titlestringPatient Zero—
videos[].statusstringOK—
videos[].urlstringhttps://www.youtube.com/watch?v=V-uIp-WuD60—
videos[].descriptionstringProvided to YouTube by Universal Music Group …—
videos[].durationinteger226—
videos[].viewsstring6722880—
videos[].view_countinteger6722880—
videos[].likesstring95077—
videos[].like_countinteger95077—
videos[].commentsnullnull—
videos[].channelobject{…}—
videos[].channel_idstringUCPC0L1d253x-KuMNwa05TpA—
videos[].channel_namestringTaylor Swift - Topic—
videos[].keywordsarray[5 items]—
videos[].is_ratings_allowedbooleantrue—
videos[].is_livebooleanfalse—
videos[].is_live_contentbooleanfalse—
videos[].is_family_safebooleantrue—
videos[].categorystringMusic—
videos[].is_privatebooleanfalse—
videos[].is_exclusivebooleanfalse—
videos[].thumbnailsarray[1 item]—
videos[].embed_urlstringhttps://www.youtube.com/embed/V-uIp-WuD60—
videos[].is_embeddablebooleantrue—
videos[].is_unlistedbooleanfalse—
videos[].publish_datestring2026-09-24T21:02:10-07:00—
videos[].published_atstring2026-09-24T21:02:10-07:00—
videos[].relative_datenullnull—
videos[].upload_datestring2026-09-24T21:02:10-07:00—
videos[].trending_positioninteger1—
videos[].previous_positionnullnull—
videos[].periods_on_chartnullnull—
videos[].chart_view_countnullnull—
videos[].artistsarray[1 item]—
videos[].release_datestring2026-09-24—
videos[].country_codestringUS—
videos[].content_typestringmusic—
videos[].sourcestringyoutube_charts—
videos[].chart_typestringTRENDING_VIDEOS—
videos[].enrichedbooleantrue—
videos[].scraped_atstring2026-10-03T04:28:40.122Z—

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-trending/";
let params = { country_code: "US" };
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.videos ?? []));
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.