API Reference

TokTik Developer API · v1

Versioned public API for persisted LIVE intelligence. All bearer-key routes are workspace-scoped. Rendered directly from the OpenAPI contract, so it cannot drift from the endpoints that actually ship. Every route below is authenticated with a bearer key and declares the scope it requires — data-plane reads under their dataset scope, and account/key-management routes under keys:manage / webhook:manage / export.

33 documented operations across 9 resources · from the bundled contract.

Rankings

get/v1/rankings/derived
Get a platform-derived rank board (methodology-versioned), with live status and the same tier-gated identity masking
rank:read200400401403429
get/v1/rankings/history
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.
rank:read200400401403429
get/v1/rankings/official
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.
rank:read200400401403429
get/v1/rankings/regions
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.
rank:read200401403429

Live & Realtime

get/v1/live/creators/{uid}/performance
List creator LIVE performance
live:read200401403429
post/v1/live/creators/{uid}/refresh
Queue an asynchronous LIVE refresh
live:read202401403429
get/v1/live/sessions
List persisted LIVE sessions
live:read200401403429
get/v1/live/sessions/{id}
Get one persisted LIVE session
live:read200401403404429
post/v1/live/stream/token
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)
live:stream201401403429503

Gifters

get/v1/creators/{handle}/gifters
List the gifters funding one creator, ranked by diamonds given to them
gifter:read200401403429
get/v1/gifters
List top observed gifters (whales) by diamonds, optionally within a window or for one creator
gifter:read200401403429
get/v1/gifters/{gifterKey}
Get one gifter's observed totals and the creators they fund (who-funds-whom)
gifter:read200401403404429

Creators

get/v1/creators/{uid}
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.
creator:read200202401403404429
get/v1/creators/{uid}/analysis
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.
creator:read200401403404429
get/v1/creators/{uid}/changes
Timeline of observed identity changes (handle, display name, avatar, bio, region, verification) for one creator
creator:read200401403404429
get/v1/creators/{uid}/followers
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`.
creator:read200202401403404429
get/v1/creators/{uid}/following
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`.
creator:read200202401403404429
get/v1/creators/{uid}/videos
List a creator's public videos with current metrics
content:read200401403404429

Content

get/v1/videos/{videoId}
Get one public video with per-video metric history
content:read200401403404429
get/v1/videos/{videoId}/comments
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.
content:read200401403404429

Trends

get/v1/trends
List public trending hashtags/sounds for a region (honest coverage)
trend:read200401403429

Exports

get/v1/exports
List workspace exports
export200401403429
post/v1/exports
Create an asynchronous dataset export
export202400401403429
get/v1/exports/{id}
Get one export job
export200401403404429
get/v1/exports/{id}/download
Download a completed export
export200401403404429

Alerts & webhooks

get/v1/alerts/rules
List webhook/alert rules
webhook:manage200401403429
post/v1/alerts/rules
Create a webhook/alert rule
webhook:manage201400401403429

Account & keys

get/v1/api-keys
List workspace API keys
keys:manage200401403429
post/v1/api-keys
Create an API key
keys:manage201400401403429
delete/v1/api-keys/{id}
Revoke a workspace API key
keys:manage200401403404429
post/v1/developer/execute
Safely execute an allow-listed API playground operation
live:read200400401403429
get/v1/entitlements
Get the workspace's plan tier, modules, limits and credit position
keys:manage200401403429
get/v1/usage
List workspace usage and per-key request charges
keys:manage200401403429