Submit TikTok Search
Start an asynchronous TikTok keyword search task and return a task_id immediately. Poll GET /tiktok/search/{task_id} for cursor-paginated results. Results are retained for ~1 hour.
Results are returned sorted by published_at descending (newest first) across pagination, full retrieval, and the signed download_url payload.
parallel_search_slices billing: by default (1), the search runs a single paginated query chain and is naturally capped near 120 items by TikTok. Setting parallel_search_slices to 2..4 runs that many concurrent chains in parallel and dedups by video id, lifting the effective ceiling. Cost scales linearly: each additional slice consumes up to ~1x the residential pages of a single search, so an N-slice request bills up to Nx the residential pages. parallel_search_slices is not a time filter — use after_datetime / before_datetime for time windows.
Usage disclosure: This endpoint does NOT accept include_usage. Billing happens in the background worker after the 202 response is sent, so there is nothing to disclose at submit time. Pass include_usage=true on GET /tiktok/search/{task_id} instead — the GET endpoint replays the final charges once task_status=completed.
task_id back immediately.
Overview
This endpoint runs an actual keyword search across TikTok (not a single profile) and returns multiple matching videos. It is asynchronous: the search runs in a background worker, and you pollGET /tiktok/search/{task_id} for cursor-paginated results. Results are retained for ~1 hour.
Results are returned sorted by published_at descending (newest first) across pagination, full retrieval, and the signed download_url payload.
Billing
Charges happen in the background worker and are disclosed on the polling endpoint (see below), not here.- Billing is
pages_fetched × residential_request. Nosearch_requestis billed for TikTok keyword search. parallel_search_slicesscales the cost linearly. By default (1) the search runs a single paginated query chain, naturally capped near ~120 items by TikTok. Setting it to2..4runs that many concurrent chains and dedups by video id, lifting the ceiling — but an N-slice request bills up to N× the residential pages of a single search.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Keyword phrase to search on TikTok (min length 2). |
max_results | integer | No | Upper bound on results the task will try to collect. 0 (default) or omitted means unlimited — pagination stops only at TikTok’s has_more=false or the upstream page cap. No hard server-side cap is enforced; you are billed per residential page actually fetched. |
parallel_search_slices | integer | No | How many concurrent paginated query chains to run and dedup (1–4, default 1). Higher values lift the result ceiling at up to ~N× the residential pages of a single search. Not a time filter — use after_datetime / before_datetime for time windows. |
after_datetime | string | No | Only include videos published on or after this boundary. Accepts YYYY-MM-DD or an ISO datetime with timezone. |
before_datetime | string | No | Only include videos published on or before this boundary. Accepts YYYY-MM-DD or an ISO datetime with timezone. |
min_likes | integer | No | Only include videos with at least this many likes. |
max_likes | integer | No | Only include videos with at most this many likes. |
min_views | integer | No | Only include videos with at least this many views. |
max_views | integer | No | Only include videos with at most this many views. |
Example Usage
Success Response (202 Accepted)
Next Steps
PollGET /tiktok/search/{task_id} to retrieve paginated results, or follow the download_url for the complete JSON once the task is completed.Authorizations
API key authentication. Include your VidNavigator API key in the X-API-Key header.
Body
Keyword phrase to search on TikTok.
2"ai tools"
Optional upper bound on results the background task will try to collect. 0 (the default) or omitted means unlimited — pagination only stops at TikTok's has_more=false or the upstream page cap. With parallel_search_slices=1 that naturally yields ~89-120 items (TikTok serves ~10 pages of ~12 items per chain); with parallel_search_slices=4 up to ~480 unique items. A positive integer caps the merged result count. No hard server-side cap is enforced — a caller asking for 3000 will be billed per residential page actually fetched (~10 pages per slice naturally) and receive whatever TikTok delivers.
x >= 0How many concurrent paginated query chains to run and dedup by video id. 1 (the default) is a single chain naturally capped near 120 items. 2..4 runs that many additional chains in parallel, lifting the effective ceiling at the cost of up to ~Nx the residential pages of a single search. Diminishing returns: 2 slices yield ~+43% unique items, 3 slices ~+22%, 4 slices ~+13% on a representative query, so 4 already saturates TikTok's natural ~480-item dedup ceiling for most queries. parallel_search_slices is not a time filter — use after_datetime / before_datetime for time windows.
1 <= x <= 42
Only include videos published on or after this boundary. Accepts YYYY-MM-DD or ISO datetime with timezone.
Only include videos published on or before this boundary. Accepts YYYY-MM-DD or ISO datetime with timezone.
x >= 0x >= 0x >= 0x >= 0
