Skip to content

Structured YouTube data: every input is optional. Cursor-paginated, 1 credit per successful call.

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

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

Terminal window
curl -G "https://api.scrapier.io/api/v2/youtube-video-thumbnail/" \
-H "X-API-Key: YOUR_API_KEY" \
--max-time 210
NameTypeRequiredDefaultDescription
X-API-Key headerstringyes—Your API key from the dashboard.
urlsstringnohttps://www.youtube.com/watch?v=dQw4w9WgXcQVIDEO MODE: watch / youtu.be / shorts / embed URL or bare 11-char id. Single lookup (next_cursor always null, result under video). Required unless channel_url is given.
channel_urlstringno—CHANNEL MODE: @handle, /channel/UC…, /c/… or /user/… URL. ~10 videos per page (newest first) under videos, paged through YouTube's own continuation token. Required 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.
channel_tabstringnovideosChannel mode: which listing to walk.
videosshortsstreams
locked in cursor
start_datestringno—Channel mode: only videos uploaded on/after (YYYY-MM-DD or ISO 8601).
locked in cursor
end_datestringno—Channel mode: only videos uploaded on/before (YYYY-MM-DD or ISO 8601).
locked in cursor
verify_thumbnailsbooleannotrueProbe every file on i.ytimg.com (real size / bytes / dropped).
locked in cursor
include_framesbooleannotrueAlso return the auto-generated frame thumbnails (frame_items).
locked in 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": {
"mode": "channel",
"channel_url": "@MrBeast",
"channel_tab": "videos",
"start_date": "2025-06-01T00:00:00Z",
"end_date": null,
"page": 1,
"page_size": 10,
"videos": [
{
"input_channel": "@MrBeast",
"position": 1,
"mode": "channel",
"video_id": "gTKS8SAwUzE",
"status": "ok",
"url": "https://www.youtube.com/watch?v=gTKS8SAwUzE",
"title": "I Survived The Most Extreme Places On Earth",
"channel_name": "MrBeast",
"channel_id": "UCX6OQ3DkcsbYNE6H8uQQuVA",
"published_at": "2026-09-05T09:00:01-07:00",
"published_at_utc": "2026-09-05T16:00:01Z",
"published_text": "Sep 5, 2026",
"duration_seconds": 1452,
"view_count": 98123456,
"is_short": false,
"thumbnail_count": 10,
"dropped": 0,
"largest": {
"id": "maxres",
"width": 1280,
"height": 720,
"format": "webp",
"ratio": "16:9",
"url": "https://i.ytimg.com/vi_webp/gTKS8SAwUzE/maxresdefault.webp",
"name": "maxresdefault",
"file": "maxresdefault.webp",
"group": "standard",
"frame": null,
"aspect": 1.7778,
"orientation": "landscape",
"megapixels": 0.922,
"aliases": [
"hq720.webp"
],
"verified": true,
"available": true,
"status_code": 206,
"bytes": 199522,
"content_type": "image/webp",
"actual_width": 1280,
"actual_height": 720,
"actual_ratio": "16:9",
"matches_declared": true,
"cache_max_age": 7200,
"last_modified": null,
"etag": "\"1757088000\"",
"is_largest": true,
"attempts": 1,
"error": null
},
"items": [
{
"id": "default",
"width": 120,
"height": 90,
"format": "webp",
"ratio": "4:3",
"url": "https://i.ytimg.com/vi_webp/gTKS8SAwUzE/default.webp",
"name": "default",
"file": "default.webp",
"group": "standard",
"frame": null,
"aspect": 1.3333,
"orientation": "landscape",
"megapixels": 0.011,
"aliases": [],
"verified": true,
"available": true,
"status_code": 206,
"bytes": 3120,
"content_type": "image/webp",
"actual_width": 120,
"actual_height": 90,
"actual_ratio": "4:3",
"matches_declared": true,
"cache_max_age": 7200,
"last_modified": null,
"etag": "\"1757088000\"",
"is_largest": false,
"attempts": 1,
"error": null
},
"... one entry per EXISTING standard size (default / medium / high / standard / maxres) in webp then jpg"
],
"dropped_items": [],
"extra_dropped_items": [],
"largest_any": null,
"original_aspect_items": [
"... oardefault / frame0 when they exist"
],
"frame_items": [
"... auto-generated frames 1/2/3 at every size when include_frames=true"
],
"summary": {
"standard_candidates": 10,
"standard_available": 10,
"standard_dropped": 0,
"extra_candidates": 3,
"extra_available": 1,
"extra_dropped": 2,
"formats": [
"webp",
"jpg"
],
"sizes_available": [
"default",
"medium",
"high"
],
"sizes_missing": [],
"total_bytes": 612345,
"verified": true,
"has_maxres": true
},
"video": {
"id": "gTKS8SAwUzE",
"url": "https://www.youtube.com/watch?v=gTKS8SAwUzE",
"title": "I Survived The Most Extreme Places On Earth",
"duration_text": "24:12",
"published_at": "2026-09-05T09:00:01-07:00",
"category": "Entertainment",
"playability_status": "OK",
"original_aspect_ratio": "16:9",
"orientation": "landscape",
"listing": {
"title": "I Survived The Most Extreme Places On Earth",
"published_text": "2 weeks ago",
"views_text": "98M views",
"view_count": 98000000,
"duration_text": "24:12",
"duration_seconds": 1452,
"badges": [],
"is_live": false,
"is_upcoming": false,
"thumbnails": [
{
"url": "https://i.ytimg.com/vi/gTKS8SAwUzE/hqdefault.jpg?sqp=...",
"width": 168,
"height": 94
}
],
"kind": "video"
},
"...": "same video object as v1 (channel, keywords, storyboards, og_image, flags)"
},
"channel": {
"id": "UCX6OQ3DkcsbYNE6H8uQQuVA",
"name": "MrBeast",
"handle": "@MrBeast",
"url": "https://www.youtube.com/channel/UCX6OQ3DkcsbYNE6H8uQQuVA",
"handle_url": "https://www.youtube.com/@MrBeast",
"description": "SUBSCRIBE FOR A COOKIE!",
"subscriber_count_text": "517M subscribers",
"subscriber_count": 517000000,
"video_count_text": "1K videos",
"video_count": 1000,
"is_family_safe": true,
"rss_url": "https://www.youtube.com/feeds/videos.xml?channel_id=UCX6OQ3DkcsbYNE6H8uQQuVA",
"avatar": [
{
"url": "https://yt3.googleusercontent.com/...=s900-c-k-c0x00ffffff-no-rj",
"width": 900,
"height": 900
}
],
"banner": [
{
"url": "https://yt3.googleusercontent.com/...",
"width": 1060,
"height": 175
}
],
"tabs": [
"Home",
"Videos",
"Shorts"
]
},
"source": {
"mode": "channel",
"input_channel": "@MrBeast",
"channel_path": "/@MrBeast",
"channel_tab": "videos",
"resolved_url": "https://www.youtube.com/@MrBeast/videos?hl=en",
"max_videos": null,
"start_date": "2025-06-01T00:00:00Z",
"end_date": null,
"position": 1,
"listing_page": 1
},
"attempts": 14,
"processing_ms": 2310,
"warnings": [],
"scraped_at": "2026-09-19T08:12:04.512Z"
}
],
"next_cursor": "eyJsayI6eyJpbmNsdWRlX2ZyYW1lcyI6ImZhbHNlIiwic3RhcnRfZGF0ZSI6IjIwMjUtMDYtMDEifSwibSI6ImNoYW5uZWwiLCJvZmYiOjEwLCJwIjoxLCJwb3MiOjEwLCJxIjoiQE1yQmVhc3QiLCJzZWVuIjpbIi4uLiJdLCJ0b2siOm51bGx9"
}
}

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

FieldTypeExampleDescription
modestringchannel—
channel_urlstring@MrBeast—
channel_tabstringvideos—
start_datestring2025-06-01T00:00:00Z—
end_datenullnull—
pageinteger1—
page_sizeinteger10—
videosarray[1 item]The results.
next_cursorstringeyJsayI6eyJpbmNsdWRlX2ZyYW1lcyI6ImZhbHNlIiwic…Pass back as cursor for the next page. null on the last page.
videos[].input_channelstring@MrBeast—
videos[].positioninteger1—
videos[].modestringchannel—
videos[].video_idstringgTKS8SAwUzE—
videos[].statusstringok—
videos[].urlstringhttps://www.youtube.com/watch?v=gTKS8SAwUzE—
videos[].titlestringI Survived The Most Extreme Places On Earth—
videos[].channel_namestringMrBeast—
videos[].channel_idstringUCX6OQ3DkcsbYNE6H8uQQuVA—
videos[].published_atstring2026-09-05T09:00:01-07:00—
videos[].published_at_utcstring2026-09-05T16:00:01Z—
videos[].published_textstringSep 5, 2026—
videos[].duration_secondsinteger1452—
videos[].view_countinteger98123456—
videos[].is_shortbooleanfalse—
videos[].thumbnail_countinteger10—
videos[].droppedinteger0—
videos[].largestobject{…}—
videos[].itemsarray[2 items]—
videos[].dropped_itemsarray[]—
videos[].extra_dropped_itemsarray[]—
videos[].largest_anynullnull—
videos[].original_aspect_itemsarray[1 item]—
videos[].frame_itemsarray[1 item]—
videos[].summaryobject{…}—
videos[].videoobject{…}—
videos[].channelobject{…}—
videos[].sourceobject{…}—
videos[].attemptsinteger14—
videos[].processing_msinteger2310—
videos[].warningsarray[]—
videos[].scraped_atstring2026-09-19T08:12:04.512Z—

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-video-thumbnail/";
let params = {};
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
  • Locked into the cursor: channel_tab, start_date, end_date, verify_thumbnails, include_frames. Set them on the first call; later pages reuse them.