Skip to content

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

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

Call GET /api/v2/tiktok-top-search/ with queries. The results are in data.items; 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-top-search/" \
-H "X-API-Key: YOUR_API_KEY" \
--data-urlencode "queries=dance challenge" \
--max-time 210
NameTypeRequiredDefaultDescription
X-API-Key headerstringyes—Your API key from the dashboard.
queriesstringyese.g. dance challengeSearch keyword for the TikTok search Top tab (videos + photo carousels). One keyword per call; required first call, ignored when cursor is supplied. One native TikTok page (~30 rows) per call; next_cursor null when TikTok has no more (guest Top search is shallow: ~60-100 rows per keyword).
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.
publish_timestringnoall-timeUpload-date filter (raw 0/1/7/30/90/180 accepted).
all-timeyesterdaythis-weekthis-monthlast-3-monthslast-6-months
locked in cursor
sort_bystringnorelevanceRanking (raw 0/1/3 accepted).
relevancemost-likeddate-posted
locked in cursor
regionstringno—ISO-2 search market sent to TikTok and, through the platform proxy, the exit country (default US). Does NOT filter rows - use filter_region.
locked in cursor
include_regionbooleannofalsetrue = load the video page of each row (~90 KB proxy traffic each) for post.ext.region (+ CDN mirrors, subtitles). Default false: fast, region null.
locked in cursor
filter_regionstringno—Client-side ISO-2 filter on post.ext.region (forces include_region). A page can be empty with a non-null next_cursor - keep following it.
locked in cursor
countintegerno30TikTok page size 1..50 (default 30).
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": {
"queries": "funny cats",
"keyword": "funny cats",
"page": 1,
"page_size": 30,
"offset": 0,
"next_offset": 30,
"has_more": true,
"search_id": "20260920101145D40385EBF1DEDE006613",
"search": {
"publish_time": "all-time",
"publish_time_value": 0,
"sort_by": "relevance",
"sort_type": 0,
"region": null,
"search_region": "US",
"include_region": true,
"filter_region": null,
"count": 30
},
"dropped": {
"duplicates": 0,
"other_cards": 1,
"filtered_out": 0
},
"warnings": [],
"items": [
{
"keyword": "funny cats",
"position": 1,
"video_id": "7687232045482806550",
"url": "https://www.tiktok.com/@cute.paws123/video/7687232045482806550",
"description": "#funny #cat #funnyvideo #catvideo #cute",
"content_type": "video",
"created_at": "2026-09-19T13:06:32.000Z",
"create_time_epoch": 1789823192,
"region": "TR",
"region_name": "Turkey",
"author_username": "cute.paws123",
"author_id": "7623372674887304214",
"author_display_name": "Cute Paws",
"play_count": 79100,
"like_count": 3919,
"comment_count": 30,
"share_count": 134,
"save_count": 194,
"repost_count": 0,
"duration_seconds": 120,
"hashtags": [
"funny",
"cat",
"funnyvideo"
],
"play_url": "https://v16-webapp-prime.us.tiktok.com/video/tos/no1a/tos-no1a-ve-0068-no/oEuIAXDQiEVIFyQD.../?a=1988&...",
"cover_url": "https://p16-common-sign.tiktokcdn-us.com/tos-no1a-p-0037-no/oMWzAqiKXXJIReLGnKQAi4AQxEAeef...~tplv-tiktokx-origin.image",
"image_urls": [],
"search": {
"publish_time": "all-time",
"publish_time_value": 0,
"sort_by": "relevance",
"sort_type": 0,
"region": null,
"search_region": "US",
"include_region": true,
"filter_region": null,
"rank": 1
},
"pagination": {
"cursor": 0,
"next_offset": 30,
"next_cursor": "sc.eyJ2IjoxLCJxIjoiZnVubnkgY2F0cyIsImMiO...",
"has_more": true,
"search_id": "20260920101145D40385EBF1DEDE006613",
"page": 1
},
"post": {
"id": "7687232045482806550",
"url": "https://www.tiktok.com/@cute.paws123/video/7687232045482806550",
"content": {
"text": "#funny #cat #funnyvideo #catvideo #cute",
"media_urls": "https://v16-webapp-prime.us.tiktok.com/video/tos/...",
"media_url_list": [
"https://v16-webapp-prime.us.tiktok.com/video/tos/...",
"..."
],
"thumbnail_url": "https://p16-common-sign.tiktokcdn-us.com/...",
"origin_cover_url": "https://p16-common-sign.tiktokcdn-us.com/...",
"dynamic_cover_url": "https://p16-common-sign.tiktokcdn-us.com/...",
"download_url": "https://v16-webapp-prime.us.tiktok.com/video/tos/...",
"duration_seconds": 120,
"width": 576,
"height": 1024,
"ratio": "540p",
"format": "mp4",
"codec": "h264",
"bitrate": 596219,
"size_bytes": 8958196,
"type": "video",
"is_photo_post": false,
"image_urls": [],
"image_count": 0,
"hashtags": [
"funny",
"cat",
"funnyvideo"
],
"mentions": []
},
"author": {
"username": "cute.paws123",
"display_name": "Cute Paws",
"avatar_url": "https://p16-common-sign.tiktokcdn-us.com/tos-maliva-avt-0068/...",
"verified": false,
"id": "7623372674887304214",
"sec_uid": "MS4wLjABAAAAnY9iTbMC4E779Wa7ZmA7iaT1-DO70dERJosDVbGFHxyKhtR59eF-Q5_qzvMD5wFO",
"signature": "Cute and Funny Cats Videos / Please Follow",
"url": "https://www.tiktok.com/@cute.paws123",
"private_account": false
},
"engagement": {
"views": 79100,
"likes": 3919,
"comments": 30,
"shares": 134,
"saves": 194,
"reposts": 0
},
"flags": {
"nsfw": null,
"spoiler": null,
"pinned": false,
"deleted": false,
"private": false,
"ad": false,
"paid_partnership": false,
"aigc": false,
"original_item": false,
"official_item": false,
"duet_enabled": true,
"stitch_enabled": true,
"share_enabled": true,
"comments_enabled": true,
"is_reviewing": false,
"is_prohibited": false
},
"published_at": "2026-09-19T13:06:32.000Z",
"ext": {
"music_id": "7687232158276684566",
"music_title": "orijinal ses",
"music_author": "Cute Paws",
"music_original": true,
"author_id": "7623372674887304214",
"author_followers": 276600,
"author_following": 2908,
"author_video_count": 122,
"author_total_likes": 21100000,
"download_count": null,
"region": "TR",
"region_name": "Turkey",
"region_source": "video_page",
"published_at_epoch": 1789823192,
"on_screen_texts": [],
"text_language": "un",
"category_type": 113,
"diversification_labels": [
"Pets",
"Animals",
"Nature"
],
"search_doc_id": "7687232045482806550",
"search_rank": 1,
"search_market": "US"
}
},
"computed": {
"engagement_rate": 0.051618,
"language": null,
"content_category": "pets",
"estimated_reach": 94920,
"engagement_rate_pct": 5.1618,
"like_rate": 0.049545,
"comment_rate": 0.000379,
"share_rate": 0.001694,
"save_rate": 0.002453,
"total_interactions": 4277,
"age_days": 0.88,
"views_per_day": 79100,
"hashtag_count": 5,
"mention_count": 0,
"caption_length": 39,
"is_short": false
},
"id": "7687232045482806550",
"desc": "#funny #cat #funnyvideo #catvideo #cute",
"create_time": "2026-09-19T13:06:32.000Z",
"desc_language": "un",
"is_top": 0,
"statistics": {
"aweme_id": "7687232045482806550",
"collect_count": 194,
"comment_count": 30,
"digg_count": 3919,
"download_count": null,
"forward_count": 0,
"lose_comment_count": 0,
"lose_count": 0,
"play_count": 79100,
"repost_count": 0,
"share_count": 134,
"whatsapp_share_count": null
},
"video": {
"duration": 120000,
"width": 576,
"height": 1024,
"ratio": "540p",
"codec_type": "h264",
"format": "mp4",
"bitrate": 596219,
"data_size": 8958196,
"has_watermark": true,
"is_bytevc1": 0,
"is_long_video": 1,
"video_id": "v24044gl0000dan8gvnog65ug20h1pm0",
"play_addr": {
"uri": "v24044gl0000dan8gvnog65ug20h1pm0",
"url_key": "v24044gl0000dan8gvnog65ug20h1pm0_h264_540p_596219",
"url_list": [
"https://v16-webapp-prime.us.tiktok.com/video/tos/...",
"https://v19-webapp-prime.us.tiktok.com/video/tos/...",
"https://www.tiktok.com/aweme/v1/play/?faid=1988&file_id=..."
],
"width": 576,
"height": 1024,
"data_size": 8958196,
"file_hash": "9d630523004ee37ee97e4fc27514379e"
},
"bit_rate": [
{
"gear_name": "adapt_lower_720_1",
"bit_rate": 621747,
"codec_type": "h265_hvc1",
"play_addr": {
"url_list": [
"..."
]
}
},
{
"gear_name": "lower_540_0",
"bit_rate": 596219,
"codec_type": "h264",
"play_addr": {
"url_list": [
"..."
]
}
}
],
"cover": {
"url_list": [
"https://p16-common-sign.tiktokcdn-us.com/..."
]
},
"download_addr": {
"url_list": [
"..."
]
},
"cla_info": {
"caption_infos": null,
"enable_auto_caption": 0
},
"...": "(full native video block)"
},
"author": {
"uid": "7623372674887304214",
"unique_id": "cute.paws123",
"nickname": "Cute Paws",
"sec_uid": "MS4wLjABAAAAnY9iTbMC4E779Wa7ZmA7iaT1-DO70dERJosDVbGFHxyKhtR59eF-Q5_qzvMD5wFO",
"follower_count": 276600,
"following_count": 2908,
"aweme_count": 122,
"total_favorited": 21100000,
"verified": false,
"signature": "Cute and Funny Cats Videos / Please Follow",
"profile_url": "https://www.tiktok.com/@cute.paws123",
"...": "(full native author block)"
},
"music": {
"id": 7687232158276685000,
"id_str": "7687232158276684566",
"title": "orijinal ses",
"author": "Cute Paws",
"duration": 120,
"play_url": "https://v16-webapp-prime.us.tiktok.com/video/tos/.../?mime_type=audio_mpeg...",
"is_original": true
},
"is_eligible_for_commission": false,
"is_paid_partnership": false,
"is_ad": false,
"shop_product_url": null,
"images": [],
"text_extra": [
{
"start": 0,
"end": 6,
"type": 1,
"sub_type": 0,
"hashtag_name": "funny",
"hashtag_id": "5424",
"user_id": "",
"user_unique_id": "",
"sec_uid": "",
"aweme_id": "",
"is_commerce": false
}
],
"cha_list": [
{
"cid": "5424",
"cha_name": "funny",
"desc": "What's so #Funny?"
},
{
"cid": "7551",
"cha_name": "cat",
"desc": ""
}
],
"image_infos": null,
"photo_title": null,
"stickers_on_item": [],
"on_screen_texts": [],
"aigc_info": {
"created_by_ai": false,
"show_aigc_label": true,
"aigc_description": ""
},
"category_type": 113,
"diversification_labels": [
"Pets",
"Animals",
"Nature"
],
"duet_enabled": true,
"stitch_enabled": true,
"share_enabled": true,
"item_comment_settings": 0,
"is_description_translatable": false,
"is_reviewing": false,
"search_doc_id": "7687232045482806550",
"scraped_at": "2026-09-20T10:11:46.454Z"
}
],
"next_cursor": "eyJpZCI6eyJtc1Rva2VuIjoiLi4uIiwib2RpbklkIjoiMCIsInR0d2lkIjoiLi4uIn0sImxrIjp7fSwicCI6MSwicG9zIjozMCwicSI6ImZ1bm55IGNhdHMiLCJ0Ijoic2MuZXlKMklqb3hMQ0p4SWpvaVpuVnVibmtnWTJGMGN5SXNJbU1pTy4uLiJ9"
}
}

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

FieldTypeExampleDescription
queriesstringfunny cats—
keywordstringfunny cats—
pageinteger1—
page_sizeinteger30—
offsetinteger0—
next_offsetinteger30—
has_morebooleantrue—
search_idstring20260920101145D40385EBF1DEDE006613—
searchobject{…}—
droppedobject{…}—
warningsarray[]—
itemsarray[1 item]The results.
next_cursorstringeyJpZCI6eyJtc1Rva2VuIjoiLi4uIiwib2RpbklkIjoiM…Pass back as cursor for the next page. null on the last page.
items[].keywordstringfunny cats—
items[].positioninteger1—
items[].video_idstring7687232045482806550—
items[].urlstringhttps://www.tiktok.com/@cute.paws123/video/76…—
items[].descriptionstring#funny #cat #funnyvideo #catvideo #cute—
items[].content_typestringvideo—
items[].created_atstring2026-09-19T13:06:32.000Z—
items[].create_time_epochinteger1789823192—
items[].regionstringTR—
items[].region_namestringTurkey—
items[].author_usernamestringcute.paws123—
items[].author_idstring7623372674887304214—
items[].author_display_namestringCute Paws—
items[].play_countinteger79100—
items[].like_countinteger3919—
items[].comment_countinteger30—
items[].share_countinteger134—
items[].save_countinteger194—
items[].repost_countinteger0—
items[].duration_secondsinteger120—
items[].hashtagsarray[5 items]—
items[].play_urlstringhttps://v16-webapp-prime.us.tiktok.com/video/…—
items[].cover_urlstringhttps://p16-common-sign.tiktokcdn-us.com/tos-…—
items[].image_urlsarray[]—
items[].searchobject{…}—
items[].paginationobject{…}—
items[].postobject{…}—
items[].computedobject{…}—
items[].idstring7687232045482806550—
items[].descstring#funny #cat #funnyvideo #catvideo #cute—
items[].create_timestring2026-09-19T13:06:32.000Z—
items[].desc_languagestringun—
items[].is_topinteger0—
items[].statisticsobject{…}—
items[].videoobject{…}—
items[].authorobject{…}—
items[].musicobject{…}—
items[].is_eligible_for_commissionbooleanfalse—
items[].is_paid_partnershipbooleanfalse—
items[].is_adbooleanfalse—
items[].shop_product_urlnullnull—
items[].imagesarray[]—
items[].text_extraarray[1 item]—
items[].cha_listarray[2 items]—
items[].image_infosnullnull—
items[].photo_titlenullnull—
items[].stickers_on_itemarray[]—
items[].on_screen_textsarray[]—
items[].aigc_infoobject{…}—
items[].category_typeinteger113—
items[].diversification_labelsarray[3 items]—
items[].duet_enabledbooleantrue—
items[].stitch_enabledbooleantrue—
items[].share_enabledbooleantrue—
items[].item_comment_settingsinteger0—
items[].is_description_translatablebooleanfalse—
items[].is_reviewingbooleanfalse—
items[].search_doc_idstring7687232045482806550—
items[].scraped_atstring2026-09-20T10:11:46.454Z—

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-top-search/";
let params = { queries: "dance challenge" };
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
  • Locked into the cursor: publish_time, sort_by, region, include_region, filter_region, count. Set them on the first call; later pages reuse them.
  • 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.