TikTok Top Search
Structured TikTok data: send queries. Cursor-paginated, 1 credit per successful call.
Overview
Section titled “Overview”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).
Request
Section titled “Request”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 210const params = new URLSearchParams({ queries: "dance challenge" });
const res = await fetch(`https://api.scrapier.io/api/v2/tiktok-top-search/?${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}`);
console.log(body.data.items);import requests
resp = requests.get( "https://api.scrapier.io/api/v2/tiktok-top-search/", headers={"X-API-Key": "YOUR_API_KEY"}, params={"queries": "dance challenge"}, timeout=210,)body = resp.json()if not resp.ok: raise RuntimeError(body.get("error") or body.get("detail"))
print(body["data"]["items"])curl -X POST "https://api.scrapier.io/api/v2/tiktok-top-search/" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"queries":"dance challenge"}' \ --max-time 210Parameters
Section titled “Parameters”| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X-API-Key header | string | yes | — | Your API key from the dashboard. |
queries | string | yes | e.g. dance challenge | Search 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). |
cursor | string | no | — | 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_time | string | no | all-time | Upload-date filter (raw 0/1/7/30/90/180 accepted). all-timeyesterdaythis-weekthis-monthlast-3-monthslast-6-months locked in cursor |
sort_by | string | no | relevance | Ranking (raw 0/1/3 accepted). relevancemost-likeddate-posted locked in cursor |
region | string | no | — | 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_region | boolean | no | false | true = 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_region | string | no | — | 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 |
count | integer | no | 30 | TikTok page size 1..50 (default 30). locked in cursor |
Advanced
| Name | Type | Default | Description |
|---|---|---|---|
use_proxy | boolean | true | Route the request through Scrapier's residential proxy pool. Default: true. Leave as is unless support tells you otherwise. |
raw_data | boolean | false | When 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. |
Response
Section titled “Response”{ "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" }}Bad input. The exact message varies by endpoint.
{ "success": false, "error": "…"}Balance below the endpoint’s price.
{ "error": "Insufficient credits. Buy more to scrape more.", "balance": 1, "required": 2}Invalid or unknown API key.
{ "detail": "Authentication service unavailable or invalid API key."}Throttled — wait for Retry-After.
{ "detail": "Request was throttled. Expected available in N seconds."}Sample from the live catalog; arrays trimmed to 3 items. Results are in data.items.
Response fields
Section titled “Response fields”| Field | Type | Example | Description |
|---|---|---|---|
queries | string | funny cats | — |
keyword | string | funny cats | — |
page | integer | 1 | — |
page_size | integer | 30 | — |
offset | integer | 0 | — |
next_offset | integer | 30 | — |
has_more | boolean | true | — |
search_id | string | 20260920101145D40385EBF1DEDE006613 | — |
search | object | {…} | — |
dropped | object | {…} | — |
warnings | array | [] | — |
items | array | [1 item] | The results. |
next_cursor | string | eyJpZCI6eyJtc1Rva2VuIjoiLi4uIiwib2RpbklkIjoiM… | Pass back as cursor for the next page. null on the last page. |
items[].keyword | string | funny cats | — |
items[].position | integer | 1 | — |
items[].video_id | string | 7687232045482806550 | — |
items[].url | string | https://www.tiktok.com/@cute.paws123/video/76… | — |
items[].description | string | #funny #cat #funnyvideo #catvideo #cute | — |
items[].content_type | string | video | — |
items[].created_at | string | 2026-09-19T13:06:32.000Z | — |
items[].create_time_epoch | integer | 1789823192 | — |
items[].region | string | TR | — |
items[].region_name | string | Turkey | — |
items[].author_username | string | cute.paws123 | — |
items[].author_id | string | 7623372674887304214 | — |
items[].author_display_name | string | Cute Paws | — |
items[].play_count | integer | 79100 | — |
items[].like_count | integer | 3919 | — |
items[].comment_count | integer | 30 | — |
items[].share_count | integer | 134 | — |
items[].save_count | integer | 194 | — |
items[].repost_count | integer | 0 | — |
items[].duration_seconds | integer | 120 | — |
items[].hashtags | array | [5 items] | — |
items[].play_url | string | https://v16-webapp-prime.us.tiktok.com/video/… | — |
items[].cover_url | string | https://p16-common-sign.tiktokcdn-us.com/tos-… | — |
items[].image_urls | array | [] | — |
items[].search | object | {…} | — |
items[].pagination | object | {…} | — |
items[].post | object | {…} | — |
items[].computed | object | {…} | — |
items[].id | string | 7687232045482806550 | — |
items[].desc | string | #funny #cat #funnyvideo #catvideo #cute | — |
items[].create_time | string | 2026-09-19T13:06:32.000Z | — |
items[].desc_language | string | un | — |
items[].is_top | integer | 0 | — |
items[].statistics | object | {…} | — |
items[].video | object | {…} | — |
items[].author | object | {…} | — |
items[].music | object | {…} | — |
items[].is_eligible_for_commission | boolean | false | — |
items[].is_paid_partnership | boolean | false | — |
items[].is_ad | boolean | false | — |
items[].shop_product_url | null | null | — |
items[].images | array | [] | — |
items[].text_extra | array | [1 item] | — |
items[].cha_list | array | [2 items] | — |
items[].image_infos | null | null | — |
items[].photo_title | null | null | — |
items[].stickers_on_item | array | [] | — |
items[].on_screen_texts | array | [] | — |
items[].aigc_info | object | {…} | — |
items[].category_type | integer | 113 | — |
items[].diversification_labels | array | [3 items] | — |
items[].duet_enabled | boolean | true | — |
items[].stitch_enabled | boolean | true | — |
items[].share_enabled | boolean | true | — |
items[].item_comment_settings | integer | 0 | — |
items[].is_description_translatable | boolean | false | — |
items[].is_reviewing | boolean | false | — |
items[].search_doc_id | string | 7687232045482806550 | — |
items[].scraped_at | string | 2026-09-20T10:11:46.454Z | — |
Pagination
Section titled “Pagination”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 };}import requests
URL = "https://api.scrapier.io/api/v2/tiktok-top-search/"HEADERS = {"X-API-Key": "YOUR_API_KEY"}params = {"queries": "dance challenge"}items = []
for _ in range(10): # each page is one billed call resp = requests.get(URL, headers=HEADERS, params=params, timeout=210) resp.raise_for_status() data = resp.json()["data"] items.extend(data.get("items") or []) if not data.get("next_cursor"): # None = last page break params = {"cursor": data["next_cursor"]}Errors
Section titled “Errors”Failed calls are free. Branch on the HTTP status and read the message from error (or detail). Full details in Errors.
| Status | Meaning | Retry? | Charged? |
|---|---|---|---|
400 | Bad or missing input. | No — fix the params | No |
401 / 403 | Missing, invalid or revoked API key. | No — fix the key | No |
402 | Out of credits (body has balance). | No — top up | No |
404 | Unknown endpoint slug. | No — check the slug | No |
429 / 503 | Busy or throttled. | Yes — after Retry-After | No |
5xx | Target site or upstream failure, or timeout. | Yes — with backoff | No |
- Locked into the cursor:
publish_time,sort_by,region,include_region,filter_region,count. Set them on the first call; later pages reuse them.
Related
Section titled “Related”- 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.