Skip to content

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

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

Call GET /api/v2/tiktok-ads-top/. The results are in data.items; send data.next_cursor back as cursor to get the next page. 10 optional parameters refine the call (see Parameters).

Terminal window
curl -G "https://api.scrapier.io/api/v2/tiktok-ads-top/" \
-H "X-API-Key: YOUR_API_KEY" \
--max-time 210
NameTypeRequiredDefaultDescription
X-API-Key headerstringyes—Your API key from the dashboard.
keywordstringno—Optional search term (login-gated by TikTok: echoed, not applied). Each call returns one leaderboard partition (<=20 ads); pass next_cursor to walk deeper into the same filter combination.
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.
countrystringnoUSISO-2 country code, validated live against TikTok's top_ads country list.
periodintegerno180Leaderboard lookback window in days.
730180
order_bystringnofor_youLeaderboard ranking axis.
for_youimpressionctrplay_2s_rateplay_6s_ratecvrlike
ad_formatstringnoAll ad typesAd format filter.
All ad typesSpark adsNon-Spark ads
ad_languagestringnoenAd language code.
like_tierintegerno—Engagement-tier bucket (1 = top tier).
industrystringnoSkincareIndustry label, matched live.
max_itemsintegerno20Ads per page (values >20 clamp to 20 = one TikTok leaderboard partition). Follow next_cursor for more; the pool is a few hundred ads for broad filters.
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": {
"keyword": null,
"country": "US",
"period": 180,
"order_by": "for_you",
"ad_format": 0,
"ad_language": "en",
"like_tier": null,
"industry": "Skincare",
"success": true,
"error": null,
"warnings": [],
"warning": null,
"items": [
{
"post": {
"id": "7160811838573182977",
"url": "https://ads.tiktok.com/business/creativecenter/topads/7160811838573182977/pc/en?countryCode=US&period=180",
"content": {
"text": "You take pride in your work. But let's face it - using subpar wax can ruin even the best intentions.",
"media_urls": "https://v16m-default.tiktokcdn.com/.../video/tos/alisg/tos-alisg-ve-0051c001-sg/....mp4",
"thumbnail_url": "https://p16-common-sign.tiktokcdn.com/....image",
"duration_seconds": 51.2
},
"author": {
"username": "honeycombwaxco",
"display_name": "honeycombwaxco",
"avatar_url": null,
"verified": false
},
"engagement": {
"views": null,
"likes": 19757,
"comments": 125,
"shares": 82,
"saves": null
},
"flags": {
"nsfw": null,
"spoiler": null,
"pinned": null,
"deleted": false
},
"published_at": null,
"ext": {
"ad": {
"ctr": 0.07,
"rank": 1,
"cost_score": 2,
"like_tier": null,
"industry": "Skincare",
"objective": "campaign_objective_conversion",
"is_spark_ad": null,
"ad_format": null,
"language": "en",
"country_code": "US",
"period_days": 180,
"video_id": "v10033g50000cdg4vn3c77u4nq4b21ig",
"video_url_540p": null,
"video_url_360p": null,
"landing_page_url": null,
"order_by": "for_you",
"detail_fetched": true
}
}
},
"computed": {
"engagement_rate": null,
"language": "en",
"content_category": "beauty",
"estimated_reach": null
}
}
],
"returned_count": 3,
"total_count": 381,
"dropped": 0,
"detail_missing": 0,
"has_more": true,
"scraped_at": "2026-09-23T09:30:00.000Z",
"next_cursor": "eyJiIjoi...base64 Bloom filter + locked filters + slot index (~1.2KB)...In0"
}
}

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

FieldTypeExampleDescription
keywordnullnull—
countrystringUS—
periodinteger180—
order_bystringfor_you—
ad_formatinteger0—
ad_languagestringen—
like_tiernullnull—
industrystringSkincare—
successbooleantrue—
errornullnull—
warningsarray[]—
warningnullnull—
itemsarray[1 item]The results.
returned_countinteger3—
total_countinteger381—
droppedinteger0—
detail_missinginteger0—
has_morebooleantrue—
scraped_atstring2026-09-23T09:30:00.000Z—
next_cursorstringeyJiIjoi...base64 Bloom filter + locked filte…Pass back as cursor for the next page. null on the last page.
items[].postobject{…}—
items[].computedobject{…}—

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-ads-top/";
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.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
  • The response data carries its own success field from the scraper. The outer success is what counts: an HTTP 200 with outer success: true is billed, even if the inner field says otherwise.
  • 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 Collection Videos — Structured TikTok data: send urls. Cursor-paginated, 1 credit per successful call.
  • TikTok Comment Replies — Structured TikTok data: send urls. Cursor-paginated, 1 credit per successful call.