Skip to content

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

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

Call GET /api/v2/tiktok-ads/ with urls. The results are in data.ads; 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/tiktok-ads/" \
-H "X-API-Key: YOUR_API_KEY" \
--data-urlencode "urls=https://library.tiktok.com/ads?region=all&adv_name=NVIDIA%20GmbH&adv_biz_ids=6891503886842987266&query_type=2&sort_type=last_shown_date,desc" \
--max-time 210
NameTypeRequiredDefaultDescription
X-API-Key headerstringyes—Your API key from the dashboard.
urlsstringyese.g. https://library.tiktok.com/ads?region=all&adv_name=NVIDIA%20GmbH&adv_biz_ids=6891503886842987266&query_type=2&sort_type=last_shown_date,descTikTok Ad Library search URL (filters: region, start_time/end_time, adv_name, adv_biz_ids, query_type, sort_type, ad_type, ad_status, ages, ad_reach, gender) or a bare keyword. One page = 12 ads (TikTok's fixed page size). Required on first call; ignored when cursor is supplied (filters are locked into it).
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.
include_detailsbooleannotrueFetch each ad's detail record (paid-by, per-region impressions, targeting). Best-effort: if TikTok rate-limits it, ads come from search-card data (detail_fetched=false) with a warning. 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": {
"urls": "https://library.tiktok.com/ads?region=all&adv_name=NVIDIA%20GmbH&query_type=2",
"page": 1,
"page_size": 12,
"total": 311,
"ads": [
{
"adId": "1874157948935201",
"adName": "Discover the new GeForce RTX",
"advertiserName": "NVIDIA GmbH",
"impressions": {
"lowerBound": 10000,
"upperBound": 100000
},
"paidBy": "NVIDIA GmbH",
"regionStats": [
{
"regionCode": "DE",
"impressions": 100000
}
],
"startUrl": "https://library.tiktok.com/ads?region=all&start_time=1786665600000&end_time=1786665600000&adv_name=NVIDIA%20GmbH&adv_biz_ids=6891503886842987266&query_type=2&sort_type=last_shown_date%2Cdesc",
"videos": [
{
"url": "https://library.tiktok.com/api/v1/cdn/.../video/...",
"coverImageUrl": "https://p16-common-sign.tiktokcdn.com/...jpeg"
}
],
"ad_id": "1874157948935201",
"ad_title": "Discover the new GeForce RTX",
"advertiser_name": "NVIDIA GmbH",
"advertiser_id": "6891503886842987266",
"first_shown_date": "2026-08-01",
"last_shown_date": "2026-08-11",
"region": "DE",
"url": "https://library.tiktok.com/ads/detail/?ad_id=1874157948935201",
"estimated_audience": "10K-100K",
"image_urls": [
"https://p16-common-sign.tiktokcdn.com/...jpeg"
],
"external_url": "https://www.nvidia.com/de-de/geforce/",
"subject": "Electronics",
"advertiser_registry_location": "Germany",
"advertiser_tiktok_username": "nvidiageforce_de",
"advertiser_tiktok_followers": "120.5K",
"target_audience_size": "7.1M-8.7M",
"targeting_age": [
{
"region": "DE",
"13-17": false,
"18-24": true,
"25-34": true,
"35-44": true,
"45-54": false,
"55+": false
}
],
"targeting_gender": [
{
"region": "DE",
"female": true,
"male": true,
"unknown": true
}
],
"detail_fetched": true,
"input_url": "https://library.tiktok.com/ads?region=all&adv_name=NVIDIA%20GmbH&query_type=2",
"scraped_at": "2026-12-01T12:00:00.000Z"
}
],
"has_more": true,
"next_cursor": "ta1.eNqrVirLz0lVslIqzs_NTVWyUqrLLy0pVbJSMjQ3NjdQ0lEqSsxLSc3PU7JSMjE0MDBQ0lEqLE..."
}
}

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

FieldTypeExampleDescription
urlsstringhttps://library.tiktok.com/ads?region=all&adv…—
pageinteger1—
page_sizeinteger12—
totalinteger311—
adsarray[1 item]The results.
has_morebooleantrue—
next_cursorstringta1.eNqrVirLz0lVslIqzs_NTVWyUqrLLy0pVbJSMjQ3N…Pass back as cursor for the next page. null on the last page.
ads[].adIdstring1874157948935201—
ads[].adNamestringDiscover the new GeForce RTX—
ads[].advertiserNamestringNVIDIA GmbH—
ads[].impressionsobject{…}—
ads[].paidBystringNVIDIA GmbH—
ads[].regionStatsarray[1 item]—
ads[].startUrlstringhttps://library.tiktok.com/ads?region=all&sta…—
ads[].videosarray[1 item]—
ads[].ad_idstring1874157948935201—
ads[].ad_titlestringDiscover the new GeForce RTX—
ads[].advertiser_namestringNVIDIA GmbH—
ads[].advertiser_idstring6891503886842987266—
ads[].first_shown_datestring2026-08-01—
ads[].last_shown_datestring2026-08-11—
ads[].regionstringDE—
ads[].urlstringhttps://library.tiktok.com/ads/detail/?ad_id=…—
ads[].estimated_audiencestring10K-100K—
ads[].image_urlsarray[1 item]—
ads[].external_urlstringhttps://www.nvidia.com/de-de/geforce/—
ads[].subjectstringElectronics—
ads[].advertiser_registry_locationstringGermany—
ads[].advertiser_tiktok_usernamestringnvidiageforce_de—
ads[].advertiser_tiktok_followersstring120.5K—
ads[].target_audience_sizestring7.1M-8.7M—
ads[].targeting_agearray[1 item]—
ads[].targeting_genderarray[1 item]—
ads[].detail_fetchedbooleantrue—
ads[].input_urlstringhttps://library.tiktok.com/ads?region=all&adv…—
ads[].scraped_atstring2026-12-01T12:00:00.000Z—

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/";
let params = { urls: "https://library.tiktok.com/ads?region=all&adv_name=NVIDIA%20GmbH&adv_biz_ids=6891503886842987266&query_type=2&sort_type=last_shown_date,desc" };
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.ads ?? []));
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 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.
  • TikTok Comment Replies — Structured TikTok data: send urls. Cursor-paginated, 1 credit per successful call.