Skip to content

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

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

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

Terminal window
curl -G "https://api.scrapier.io/api/v2/tiktok-trending-videos/" \
-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. USCountry: US, JP, VN, TH or ID (the countries TikTok Creative Center ranks videos for). Required on first call; ignored when cursor is supplied.
USJPVNTHID
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.
sort_bystringnohotRanking metric: hot/views (video views), engagement (alias like/share/comment), six_second_views. Locked into the cursor.
hotviewsengagementsix_second_viewsviewlikesharecomment
periodstringno77 (videos created in last 7 days), 30 (last 30 days), weekly, monthly. Deeper pages walk older ranking windows. Locked into the cursor.
730weeklymonthly
content_tagstringno—Optional content filter (comma-separated): beauty, fashion, food, lifestyle, tech. Empty = all. Locked into the cursor.
organic_onlybooleannofalseOnly organic (non-promoted) videos. Locked into the cursor.
page_sizeintegerno25Videos per page (1-100). Locked into the cursor.
include_detailsbooleannofalsetrue = add tiktok.com stats (likes, shares, comments, saves, plays, duration) per video, fetched in parallel within the call ~24 s budget; a video whose stats miss the budget is still returned with stats null and stats_pending=true (Creative Center views/engagement always present). false = listing only (~3-5 s). 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",
"period": "7",
"sort_by": "views",
"page": 1,
"page_size": 25,
"videos": [
{
"country_code": "US",
"cover": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/o81vAiZAY0BgmWspOa5ZIkVEAiWDCTBErj4A2~tplv-tiktokx-origin.image",
"duration": 66,
"id": "7680342145466780941",
"item_id": "7680342145466780941",
"item_url": "https://www.tiktok.com/@renz.sadiwa/video/7680342145466780941",
"region": "United States",
"title": "3 NEW Gemini Live Features That Should Not Be This Good",
"diggCount": 23700,
"shareCount": 844,
"commentCount": 212,
"playCount": 66100000,
"collectCount": 3356,
"videoUrl": "https://v16-webapp-prime.tiktok.com/video/tos/alisg/...",
"video_id": "7680342145466780941",
"url": "https://www.tiktok.com/@renz.sadiwa/video/7680342145466780941",
"description": "3 NEW Gemini Live Features That Should Not Be This Good",
"author_username": "renz.sadiwa",
"author_nickname": "Renz Sadiwa",
"author_id": "6757836093687514118",
"author_followers": 208907,
"author_avatar": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/fd28960c3222a012607ffe91574d4134~tplv-tiktokx-cropcenter:300:300.jpeg",
"author_bio": "Tech | Lifestyle",
"create_time": "2026-08-31T23:30:28Z",
"play_count": 66100000,
"like_count": 23700,
"video_views": 39218761,
"video_views_lifetime": 52968271,
"organic_video_views": 489679,
"organic_video_views_lifetime": 1166715,
"engagement_rate": 0.000392,
"engagement_rate_lifetime": 0.000382,
"six_seconds_vtr": 0.012569,
"six_seconds_vtr_lifetime": 0.012242,
"cover_avif": "https://p16-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/o81vAiZAY0BgmWspOa5ZIkVEAiWDCTBErj4A2~tplv-photomode-zoomcover-tcm:720:720.avif",
"rank": 1,
"period": "7",
"sort_by": "views",
"content_tag": "all",
"organic_only": false,
"ranking_window_end": "2026-09-28T00:00:00Z",
"ranking_window_index": 0,
"scraped_at": "2026-10-01T12:00:00.000Z",
"input_country": "US",
"stats_pending": false
}
],
"next_cursor": "tv1.eNpVjk0KgzAQhe8y6yzM1L8DdNdlj1B0YhtQoyamFfHuJlHaLoZh3ve-YZ5QaYdQFKUWbbOlhh8CLeEBwj2nr3G7kTAJcE5TZOlo5dPxH0pNFE0mnA8MiPAy4j0SwMn9VQ5mlkDq3Zx0zLVz52Y8WjiUL"
}
}

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

FieldTypeExampleDescription
country_codestringUS—
periodstring7—
sort_bystringviews—
pageinteger1—
page_sizeinteger25—
videosarray[1 item]The results.
next_cursorstringtv1.eNpVjk0KgzAQhe8y6yzM1L8DdNdlj1B0YhtQoyamF…Pass back as cursor for the next page. null on the last page.
videos[].country_codestringUS—
videos[].coverstringhttps://p16-common-sign.tiktokcdn-us.com/tos-…—
videos[].durationinteger66—
videos[].idstring7680342145466780941—
videos[].item_idstring7680342145466780941—
videos[].item_urlstringhttps://www.tiktok.com/@renz.sadiwa/video/768…—
videos[].regionstringUnited States—
videos[].titlestring3 NEW Gemini Live Features That Should Not Be…—
videos[].diggCountinteger23700—
videos[].shareCountinteger844—
videos[].commentCountinteger212—
videos[].playCountinteger66100000—
videos[].collectCountinteger3356—
videos[].videoUrlstringhttps://v16-webapp-prime.tiktok.com/video/tos…—
videos[].video_idstring7680342145466780941—
videos[].urlstringhttps://www.tiktok.com/@renz.sadiwa/video/768…—
videos[].descriptionstring3 NEW Gemini Live Features That Should Not Be…—
videos[].author_usernamestringrenz.sadiwa—
videos[].author_nicknamestringRenz Sadiwa—
videos[].author_idstring6757836093687514118—
videos[].author_followersinteger208907—
videos[].author_avatarstringhttps://p16-common-sign.tiktokcdn-us.com/tos-…—
videos[].author_biostringTech | Lifestyle—
videos[].create_timestring2026-08-31T23:30:28Z—
videos[].play_countinteger66100000—
videos[].like_countinteger23700—
videos[].video_viewsinteger39218761—
videos[].video_views_lifetimeinteger52968271—
videos[].organic_video_viewsinteger489679—
videos[].organic_video_views_lifetimeinteger1166715—
videos[].engagement_ratenumber0.000392—
videos[].engagement_rate_lifetimenumber0.000382—
videos[].six_seconds_vtrnumber0.012569—
videos[].six_seconds_vtr_lifetimenumber0.012242—
videos[].cover_avifstringhttps://p16-common-sign.tiktokcdn-us.com/tos-…—
videos[].rankinteger1—
videos[].periodstring7—
videos[].sort_bystringviews—
videos[].content_tagstringall—
videos[].organic_onlybooleanfalse—
videos[].ranking_window_endstring2026-09-28T00:00:00Z—
videos[].ranking_window_indexinteger0—
videos[].scraped_atstring2026-10-01T12:00:00.000Z—
videos[].input_countrystringUS—
videos[].stats_pendingbooleanfalse—

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/tiktok-trending-videos/";
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.
  • TikTok Ad Library Leads — Structured TikTok data: every input is optional. Single lookup, 3 credits per successful call.
  • TikTok Ad Library — Structured TikTok data: send urls. Cursor-paginated, 1 credit per successful call.
  • TikTok Ads Top — Structured TikTok data: every input is optional. Cursor-paginated, 1 credit per successful call.
  • TikTok Collection Videos — Structured TikTok data: send urls. Cursor-paginated, 1 credit per successful call.