API Reference

List the per-game gaming boards a region offers — the source for the `game` parameter of board=gaming_game reads, built from captured switcher evidence, never a hardcoded list. `offered` games are readable now; `not_offered` names games TikTok has pulled. An empty list means the region runs only the aggregate gaming board (TikTok has not enabled per-game tabs there). Exposes no creator identity, so no masking applies.

List retained periods of an official rank board, newest first, with cursor pagination. Each period carries its own coverage status — partially captured periods are shown, not hidden. Identity masking follows the caller's plan tier, never the public teaser rule. The `shopping_daily`/`shopping_weekly` boards additionally require the `shop:read` scope (on top of `rank:read`); `board=gaming_game` requires `game`.

Region movers (LT1.3): the creators whose rank changed most since the board's previous period, split into `gainers` (moved up) and `losers` (moved down), each biggest-move-first and capped by `limit` (1..99, default 20). Derived from the same official board read, so identity is masked by the caller's plan tier exactly as /v1/rankings/official — never an unmask backdoor. A gated/unpublished board returns empty lists. Shopping boards additionally require `shop:read`; `board=gaming_game` requires `game`.

Get an official (TikTok-observed) rank board with avatar, live status, movement, and honest coverage. Gated boards distinguish incomplete collection (not-covered) from boards TikTok does not publish in that region (not-offered). Creator identity (handle/nickname/avatar) is masked below the unlock tier; rank/score/movement/live always show. Board keys include `hourly`, `daily`, `popular_live`, `gaming_daily`, `gaming_weekly`, the per-game gaming board `gaming_game` (requires the `game` parameter — a game_key from /v1/rankings/gaming/games; the `game` parameter is refused on every other board), the `league_a1`..`league_d5` league boards, and the LIVE Shopping boards `shopping_daily` (rank_type 29, daily, SEA incl. SG) and `shopping_weekly` (rank_type 6, weekly Mon-reset, US/UK/BR/JP). Shopping score is ranking POINTS (not GMV/currency) and its two cadences are not comparable as one unit. The two shopping boards additionally require the `shop:read` scope (on top of `rank:read`).

List the regions a rank board can be read for, each with its coverage, its currently offered captured board keys, and `notOfferedBoards` — the boards proven absent from TikTok's product there. Disable only what `notOfferedBoards` names: a board missing from `boards` may simply be one we have not captured yet. Regions are BUCKET keys (US+, MENA, LATAM, DE+) — not ISO country codes, which match no board — and the list is built from captured availability, not from the crawl configuration.

List creator LIVE performance

Get the LIVE video playback sources (HLS/FLV) for a creator who is live now (D2.12). `live:stream`, not `live:read` — this is the video, not the metrics. The customer's browser fetches the stream directly from TikTok's CDN (`source: tiktok-cdn`). Answers `200` with `status: no_playback`/`offline` when there is nothing to play, and `202` (poll the same URL) while a room is being resolved.

Queue an asynchronous LIVE refresh

List persisted LIVE sessions

Get one persisted LIVE session

Mint a short-lived realtime WS handshake token (present it via the Authorization header or the Sec-WebSocket-Protocol subprotocol when dialing wss://<host>/v1/live/stream — never in the URL)

List the gifters funding one creator in a window, ranked by diamonds given to them

List top observed gifters (whales) by diamonds in a window (24h/7d/30d), optionally for one creator

Get one gifter's observed totals in a window and the creators they fund (who-funds-whom)

Search/browse the already-observed creator set, most-followed first (never a live TikTok search). An empty `q` browses the most-followed observed creators; a `q` filters by handle/display-name substring (case-insensitive). Suppressed creators are excluded. **LT2.1 recruiting finder:** without `q`, the filters `region`, `minFollowers`, `liveNow` and `sort` (`followers` default | `rank` = the region's current Daily board order) browse the pool with `cursor`/`nextCursor` pagination. Creator identity (handle/name/avatar) is masked below the `agency` tier (`masked:true`, `unmaskTier`); `region`/`followerCount`/`isLive`/`verified` always show. A `q` search is never masked.

Get a public creator profile with metric history. An account we have no fresh copy of is resolved from TikTok on demand (billed `profile-resolve`); a store hit is billed `cached-read`. A resolve that exceeds the synchronous budget answers 202 — poll this same URL.

Full-analysis report for one creator (R4.4): engagement rates, posting cadence, top videos, audience signal from collected comments and follower growth — all derived from stored observations, never fetched at read time. Coverage is always `partial` and `limits` names each gap.

Timeline of observed identity changes (handle, display name, avatar, bio, region, verification) for one creator

List a creator's followers (R4.5). Same collection path as `/following`, but TikTok streams followers newest-first and never declares an end, so the response is always a SAMPLE of the most recent followers — compare `storedCount` with `totalReported`.

List the accounts a creator follows (R4.5). Collected on demand through the signed mobile list API when we hold nothing fresh (billed `follow-list-resolve`); a store hit is `cached-read`. The first call for an uncollected account normally answers 202 — poll this same URL. Paginate with the opaque `cursor`.

Get a creator's active story tray (D6.1). Content, so it is `content:read` (grouped with videos, not the profile read). Resolves store-first like the profile read, then fetches the tray FRESH through the signed mobile path — stories are ephemeral and never stored. Degrades to an empty tray when no signed credential is configured. Metered `cached-read`.

List a creator's public videos with current metrics

Get one public video with per-video metric history

List a public video's comments (R4.3). Collected anonymously from TikTok on demand when we hold nothing fresh (billed `comments-collect`); a store hit is billed `cached-read`. Paginate with the opaque `cursor` returned by the previous page, and pass `parentCommentId` to page one comment's replies.

List public trending hashtags/sounds for a region (honest coverage)

List workspace exports

Create an export (format csv|xlsx). Datasets: live_sessions, rankings (needs board+region), gifters, creator_roster. Rankings honours the caller's tier identity-mask (export is not an unmask backdoor). 400 invalid_format/invalid_request; 403 export_format_not_entitled if the plan lacks the format

Get one export job

Download a completed export (CSV or XLSX, with a format-appropriate content-type)

List the workspace's watchlist creators (D6.1). Sold under `watchlist:manage`; not credit-metered.

Add a creator to the workspace watchlist (D6.1). `409 watchlist_full` at the 25-entry cap; `409` on a duplicate handle (case-insensitive).

Remove a creator from the workspace watchlist (D6.1)

List webhook/alert rules

Create a webhook/alert rule. Any webhook channel's signing secret is returned ONCE in `webhookSecrets` — store it now.

Delete a webhook/alert rule

Update a webhook/alert rule (partial). Returns the updated rule.

Fire a synthetic test event through a rule's channels to verify delivery (does not consume the live event stream)

List workspace API keys (metadata only — never a secret)

Create an API key. The full secret token is returned ONCE in `token` — store it now.

Revoke a workspace API key

Get the workspace's plan tier, modules, limits (incl. exportFormats) and credit position

List workspace usage and per-key request charges for a billing period