Get TikTok Search Result
Poll an async TikTok keyword search task and retrieve cursor-paginated normalized result items.
This endpoint does not consume credits — polling is free.
Usage disclosure: Set include_usage=true to receive a usage block describing the charges the background worker recorded for this task. Returned only when task_status=completed (processing tasks haven’t finished billing; failed tasks have all charges refunded). Charges are pages_fetched × residential_request (no search_request is billed for TikTok keyword search).
Overview
This is the second half of the TikTok keyword search workflow. Use it after you submit a search withPOST /tiktok/search.
It serves three purposes:
- check whether the task is still running
- retrieve the matched videos page by page (sorted by
published_at, newest first) - get a temporary
download_urlfor the full JSON result when available
Request Parameters
| Parameter | In | Required | Description |
|---|---|---|---|
task_id | path | Yes | Task ID returned by POST /tiktok/search |
cursor | query | No | Opaque pagination cursor from a previous response |
limit | query | No | Maximum number of items to return, between 1 and 500. Default is 50. |
include_usage | query | No | When true and task_status=completed, attach a usage block describing the charges the background worker recorded (pages_fetched × residential_request; no search_request for TikTok keyword search). |
Usage Disclosure
Because billing happens in the background worker, the submit endpoint cannot disclose usage. Instead, passinclude_usage=true here:
- Returned only when
task_status=completed(processing tasks haven’t finished billing; failed tasks have all charges refunded). - Charges are
pages_fetched × residential_request. Nosearch_requestis billed for TikTok keyword search.
Polling Lifecycle
Thetask_status field will be one of:
processing: the search is still runningcompleted: the search finished and results are readyfailed: the search ended with an error (all charges refunded)
results will be empty and download_url will usually be null.
Example Requests
Example Completed Response
usage block appears only when include_usage=true and task_status=completed.Understanding the Response
stats
pages_fetched: number of TikTok pages fetched (this is what you are billed for, asresidential_request)results_count: total normalized items collectednext_search_cursor: internal upstream cursor, ornullwhen exhausted
results
Each item is a normalized TikTok video with id, description, timestamp, published_at (UTC ISO 8601), author, stats (views/likes/comments/shares/collects), music, duration, hashtags, and url. Items are sorted by published_at descending; items without a timestamp go last.
download_url
When present, a short-lived signed URL pointing to the full search result as one JSON file (same shape as the paginated results, but unsliced). null when the task hasn’t finished or signed URLs aren’t configured — paginate through results instead.
Error Cases
400: invalid request (e.g. bad cursor)404: task does not exist, expired, or does not belong to the current user
Tips
- poll every few seconds while
task_statusisprocessing - switch to
download_urlfor large completed jobs - tasks expire after about 1 hour — use
expires_atto avoid polling expired tasks - call the endpoint again later if you need a freshly minted
download_url
Authorizations
API key authentication. Include your VidNavigator API key in the X-API-Key header.
Path Parameters
Query Parameters
1 <= x <= 500When true and task_status=completed, attach a usage block describing the charges the background worker recorded (pages_fetched × residential_request; no search_request for TikTok keyword search).

