TikTok Search Users
Structured TikTok data: send queries. Cursor-paginated, 1 credit per successful call.
Overview
Section titled “Overview”Call GET /api/v2/tiktok-search-users/ with queries. The results are in data.users; send data.next_cursor back as cursor to get the next page. 9 optional parameters refine the call (see Parameters).
Request
Section titled “Request”curl -G "https://api.scrapier.io/api/v2/tiktok-search-users/" \ -H "X-API-Key: YOUR_API_KEY" \ --data-urlencode "queries=cooking" \ --max-time 210const params = new URLSearchParams({ queries: "cooking" });
const res = await fetch(`https://api.scrapier.io/api/v2/tiktok-search-users/?${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.users);import requests
resp = requests.get( "https://api.scrapier.io/api/v2/tiktok-search-users/", headers={"X-API-Key": "YOUR_API_KEY"}, params={"queries": "cooking"}, timeout=210,)body = resp.json()if not resp.ok: raise RuntimeError(body.get("error") or body.get("detail"))
print(body["data"]["users"])curl -X POST "https://api.scrapier.io/api/v2/tiktok-search-users/" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"queries":"cooking"}' \ --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. cooking | Search keyword -> the accounts TikTok's user search returns (guest). One native page (10 accounts) per call. Required first call, ignored when cursor is supplied. |
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. |
include | string | no | — | 'profile' hydrates every row of the page (bio, ISO region, bio_link, business_category, following / video counts). profile locked in cursor |
country | string | no | — | ISO 3166-1 alpha-2: only accounts whose public region matches; the page then holds up to max_items (1..20, default 8) in-country accounts, region-checking up to country_scan_limit (10..60, default 20) candidates per call. locked in cursor |
max_items | integer | no | 8 | Country mode only: in-country page size (1..20, default 8). Ignored otherwise (the search API serves 10 per page). locked in cursor |
region | string | no | US | Search market (ISO-2) sent to TikTok. Default: country, else US. locked in cursor |
trim | boolean | no | false | true drops the always-null wrappers around each native user_info row. locked in cursor |
country_scan_limit | integer | no | 20 | Country mode: candidates region-checked per call. locked in cursor |
region_samples | integer | no | 2 | Newest videos checked per account for the region vote. locked in cursor |
hydrate_passes | integer | no | 3 | Retry passes for rows left incomplete by transient rate limits. 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": "cooking", "page": 1, "page_size": 10, "offset": 0, "next_offset": 10, "has_more": true, "search_id": "202609201740006BDFE2548C230506FC79", "scanned": 10, "scanned_this_call": 10, "search_calls": 1, "country": null, "country_name": null, "region": "US", "include": null, "trim": false, "hydration": null, "warnings": [], "duration_ms": 1050, "users": [ { "keyword": "cooking", "position": 1, "user_id": "6780483742282875910", "username": "cookingwithayeh", "nickname": "Cooking with Ayeh", "followers": 2300000, "region": null, "region_name": null, "verified": false, "private": false, "profile_url": "https://www.tiktok.com/@cookingwithayeh", "author": { "id": "6780483742282875910", "username": "cookingwithayeh", "display_name": "Cooking with Ayeh", "avatar_url": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/...", "bio": null, "verified": false, "followers": 2300000, "following": 0, "posts_count": 0, "likes_count": 45000000, "url": "https://www.tiktok.com/@cookingwithayeh", "location": null, "private": false }, "user": { "id": "6780483742282875910", "name": "cookingwithayeh", "profile_url": "https://www.tiktok.com/@cookingwithayeh", "nick_name": "Cooking with Ayeh", "verified": false, "signature": null, "bio_link": null, "avatar": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/...", "commerce_user_info": { "commerce_user": false }, "private_account": false, "room_id": "", "tt_seller": false, "create_time": null, "has_active_story": false, "following": 0, "friends": 0, "fans": 2300000, "heart": 45000000, "video": 0, "digg": 0, "follow_dataset_url": null, "original_avatar_url": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/..." }, "stats": { "follower_count": 2300000, "following_count": 0, "likes_count": 45000000, "video_count": 0, "friend_count": 0, "digg_count": 0, "search_follower_count": 2300000, "search_total_favorited": 45000000 }, "extra": { "sec_uid": "MS4wLjABAAAA...", "short_id": "6780483742282875910", "custom_verify": "", "enterprise_verify_reason": "", "search_user_name": "cookingwithayeh", "search_user_desc": "Easy healthy recipes anyone can make ❤️", "search_highlight": null, "relative_users": null, "cv_level": null, "user_mode": null, "language": null, "location_name": null, "region_votes": {}, "latest_video_ids": [], "avatar_thumb": "https://p16-common-sign.tiktokcdn.com/tos-maliva-avt-0068/...", "avatar_medium": null, "avatar_larger": null, "hydration_status": null, "hydration_error": null }, "native": { "user_info": { "uid": "6780483742282875910", "nickname": "Cooking with Ayeh", "unique_id": "cookingwithayeh", "follower_count": 2300000, "total_favorited": 45000000, "sec_uid": "MS4wLjABAAAA..." }, "position": null, "uniqid_position": null, "effects": null, "musics": null, "items": null, "mix_list": null, "challenges": null }, "search": { "page": 1, "cursor_sent": 0, "next_offset": 10, "next_cursor": "sc.eyJ2IjoxLCJxIjp7ImtleXdvcmQiOiJjb29raW5nIiwiY3Vyc29yIjoiMTAiLCJzZWFyY2hfaWQiOiIyMDI2MDkyMDE3NDAwMDZCREZFMjU0OEMyMzA1MDZGQzc5In19", "has_more": true, "search_id": "202609201740006BDFE2548C230506FC79", "rid": "202609201740006BDFE2548C230506FC79", "region": "US", "country": null, "country_name": null, "include": null, "trim": false, "scanned": 10 }, "hydration": null, "scraped_at": "2026-09-20T09:40:03.391Z" } ], "next_cursor": "eyJsayI6e30sIm9mZiI6MTAsInAiOjEsInBvcyI6MTAsInEiOiJjb29raW5nIiwicyI6WyI2NzgwNDgzNzQyMjgyODc1OTEwIiwi..." }}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.users.
Response fields
Section titled “Response fields”| Field | Type | Example | Description |
|---|---|---|---|
queries | string | cooking | — |
page | integer | 1 | — |
page_size | integer | 10 | — |
offset | integer | 0 | — |
next_offset | integer | 10 | — |
has_more | boolean | true | — |
search_id | string | 202609201740006BDFE2548C230506FC79 | — |
scanned | integer | 10 | — |
scanned_this_call | integer | 10 | — |
search_calls | integer | 1 | — |
country | null | null | — |
country_name | null | null | — |
region | string | US | — |
include | null | null | — |
trim | boolean | false | — |
hydration | null | null | — |
warnings | array | [] | — |
duration_ms | integer | 1050 | — |
users | array | [1 item] | The results. |
next_cursor | string | eyJsayI6e30sIm9mZiI6MTAsInAiOjEsInBvcyI6MTAsI… | Pass back as cursor for the next page. null on the last page. |
users[].keyword | string | cooking | — |
users[].position | integer | 1 | — |
users[].user_id | string | 6780483742282875910 | — |
users[].username | string | cookingwithayeh | — |
users[].nickname | string | Cooking with Ayeh | — |
users[].followers | integer | 2300000 | — |
users[].region | null | null | — |
users[].region_name | null | null | — |
users[].verified | boolean | false | — |
users[].private | boolean | false | — |
users[].profile_url | string | https://www.tiktok.com/@cookingwithayeh | — |
users[].author | object | {…} | — |
users[].user | object | {…} | — |
users[].stats | object | {…} | — |
users[].extra | object | {…} | — |
users[].native | object | {…} | — |
users[].search | object | {…} | — |
users[].hydration | null | null | — |
users[].scraped_at | string | 2026-09-20T09:40:03.391Z | — |
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-search-users/";let params = { queries: "cooking" };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.users ?? [])); if (!data.next_cursor) break; // null = last page params = { cursor: data.next_cursor };}import requests
URL = "https://api.scrapier.io/api/v2/tiktok-search-users/"HEADERS = {"X-API-Key": "YOUR_API_KEY"}params = {"queries": "cooking"}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("users") 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:
include,country,max_items,region,trim,country_scan_limit,region_samples,hydrate_passes. Set them on the first call; later pages reuse them. - This endpoint can take several minutes. Set your client timeout to at least 210 seconds.
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.