Skip to main content
POST
Submit a TikTok LIVE search (async)
Find TikTok LIVE rooms broadcasting right now for a keyword, with their stream URLs, and get a task_id back immediately.

Overview

This endpoint searches TikTok’s LIVE tab: it returns the rooms that are live at the moment the search runs, not past videos. Each room comes with its author, live counters (current viewers, likes, …), hashtags, category and playback URLs (FLV and HLS by quality, plus an audio-only stream). It is asynchronous: you poll GET /tiktok/live/search/{task_id} for cursor-paginated rooms, or wait for the webhook. Results are retained for ~1 hour.
  • Rooms keep TikTok’s ranking.
  • Results are localized to country (default us): the same keyword returns different rooms in different countries.
  • TikTok serves about 50 rooms per keyword. A keyword with no LIVE room in that country at that moment completes with zero results.
  • A search usually takes 20 to 50 seconds.
Looking for regular TikTok videos? Use TikTok Keyword Search. LIVE search returns rooms that are broadcasting now, each shaped like a keyword search result (id, author, stats, hashtags) plus LIVE-only fields.

Billing

  • 1 residential_request per 30 rooms TikTok returned (stats.rooms_fetched, including rooms past max_results), minimum 1 per search. A keyword typically yields up to about 45 rooms, so 1 or 2 residential requests.
  • Stream URLs cost nothing extra: they come in the same TikTok response.
  • No search_request is billed. A failed search is fully refunded.
Usage disclosure: this endpoint does not accept include_usage. Billing happens after the 202 response is sent. Pass include_usage=true on GET /tiktok/live/search/{task_id} instead.

Request Parameters

Example Usage

Success Response (202 Accepted)

Get the result

GET /tiktok/live/search/{task_id} — poll this endpoint with the task_id (or the check_status_url) returned above, or wait for the webhook notification. Polling does not consume credits.
The playground above only covers the submit request. Call the result endpoint with cURL or your HTTP client.

Request Parameters

Polling Lifecycle

  • processing: the search is still running (results is empty)
  • completed: the rooms are ready
  • failed: the search ended with an error (all charges refunded)

Example Requests

Example Completed Response

Understanding the Response

stats

  • rooms_fetched: distinct rooms TikTok returned, including any past max_results. This is what is billed (1 residential_request per 30).
  • results_count: rooms in results
  • has_more: whether TikTok had more rooms when the search stopped
  • pages_fetched: TikTok pages fetched (up to 50 rooms each)
  • country: same as country

results

Each room is shaped like a keyword search result, plus LIVE-only fields:

stream_urls

The URLs play while the LIVE is on and stop when it ends, whatever expires_at says. They work in players such as VLC, ffplay or ffmpeg (FLV and HLS), and in browsers through hls.js (HLS).

download_url

When present, a short-lived signed URL to the full result as one JSON file (same shape as the paginated results, but unsliced). Call the endpoint again to mint a fresh one.

error

Present when task_status is failed: an object with error (a code you can branch on, e.g. search_failed), message and http_status. See Errors.

webhook

Delivery state of the task’s webhook notification (status, attempts, response_status, last_error, delivered_at), or null when no webhook applies.

Error Cases

Tips

  • LIVE rooms change by the minute: run the search when you need the rooms, and read the stream URLs soon after.
  • Try several keywords and countries: a keyword can have no LIVE room in one country and dozens in another.
  • stats.viewers is a snapshot taken when the search ran.

Authorizations

X-API-Key
string
header
required

API key authentication. Include your VidNavigator API key in the X-API-Key header.

Body

application/json
query
string
required

Keyword phrase to search LIVE rooms for.

Minimum string length: 2
Example:

"gaming"

max_results
integer
default:0

Upper bound on rooms collected. 0 (the default) means as many as TikTok serves, about 50 per keyword.

Required range: x >= 0
country
enum<string>
default:us

Country whose LIVE rooms you get (ISO 3166-1 alpha-2, lowercase or uppercase), one of the supported countries. Default us.

Available options:
al,
am,
ao,
ar,
at,
au,
az,
ba,
be,
bf,
bg,
bj,
bo,
br,
bw,
by,
ca,
cd,
ch,
ci,
cl,
cm,
co,
cr,
cy,
cz,
de,
dk,
do,
ec,
ee,
es,
fi,
fj,
fr,
gb,
ge,
gh,
gr,
gt,
hn,
hr,
ht,
hu,
id,
ie,
il,
is,
it,
jm,
jp,
ke,
kg,
kr,
kz,
lk,
lt,
lu,
lv,
md,
me,
mg,
mk,
ml,
mn,
mt,
mu,
mw,
mx,
my,
mz,
na,
ne,
ng,
ni,
nl,
no,
np,
nz,
pa,
pe,
pg,
ph,
pl,
pr,
pt,
py,
ro,
rs,
rw,
se,
sg,
si,
sk,
sn,
sv,
tg,
th,
tj,
tr,
tt,
tw,
tz,
ua,
ug,
us,
uy,
uz,
ve,
vn,
za,
zm,
zw
Example:

"gb"

include_stream_urls
boolean
default:true

Return each room's playback URLs in stream_urls (FLV and HLS by quality, plus an audio-only FLV). On by default; they come at no extra cost. Pass false to leave them out.

webhook_url
string<uri>

Where to POST the result when the task finishes. Overrides the account-level default configured in Studio → API; pass an empty string to opt this task out of that default. Must be a publicly reachable https URL. The event is a notification, not the payload: it carries stats and tells you to read the rooms from check_status_url. See https://docs.vidnavigator.com/guides/webhooks

Example:

"https://example.com/hooks/vidnavigator"

Response

Task accepted and queued.

status
enum<string>
Available options:
success
data
object