Developer API
TikTok LIVE API: rankings, gifters, agencies and realtime events
Toktik's Developer API serves the TikTok LIVE data it observes — ranking boards, gifter boards, the agency directory, per-creator LIVE performance and a realtime event stream — over REST and WebSocket, with official JavaScript and Python SDKs. It is an independent API, not TikTok's own.
Updated
Make your first request
Data reads are authenticated GET requests with your API key as a Bearer token. The response wraps the data with its provenance: when it was observed, from which source and how complete it is.
curl -s "https://api.toktikhq.com/v1/rankings/official?board=daily®ion=VN" \
-H "Authorization: Bearer $TOKTIK_API_KEY"Prefer a client library? Follow the Python guide or the Node.js guide, or the quickstart to mint a key.
What the API returns
Each dataset needs one scope on the key, and each has a method on the official SDKs.
| Dataset | Scope | SDK |
|---|---|---|
| Rankings boards (official) | rank:read | rankings |
| LIVE Shopping ranking boards (daily + weekly) | shop:read | — |
| LIVE Pro creator directory (per-region ✦ membership) | live-pro:read | livePro |
| TikTok LIVE agency directory (contact details unlock on the Agency plan) | agencies:read | agencies |
| Per-creator LIVE performance | live:read | live |
| Realtime WebSocket LIVE events (any creator) | live:stream | live |
| Gifter / whale intelligence | gifter:read | gifters |
| Creator profile, change history, analysis, follow lists | creator:read | creators |
| A creator's videos, one video, its comments & story tray | content:read | content |
| Trending hashtags & sounds | trend:read | trends |
Toktik API or a LIVE connector?
“TikTok LIVE connector” libraries and Toktik solve different problems. The choice is between running a collector yourself and calling a hosted API:
| Aspect | Running your own collector | Toktik Developer API |
|---|---|---|
| Where it runs | In your own process or servers: you run the collector. | Hosted: Toktik runs the collection and you call an API. |
| Data | Whatever the collector you run captures, typically the events of the rooms it connects to. | Ranking boards, gifter boards, the agency directory, per-creator history and decoded realtime events. |
| Scale | One connection per room you follow, from your infrastructure. | Many creators over one stream, within your plan's connection and room-minute caps. |
| Upkeep | You own upkeep when TikTok changes something. | Toktik maintains the collection; you depend on a versioned /v1 contract. |
| Cost | Your hosting and engineering time, plus whatever the library you choose costs. | Free tier, then prepaid credits with hard caps. |
Run your own collector if you only need the raw events of a room or two and want full control. Use the Toktik API when you need rankings, gifter or agency data, history, or to follow many creators without operating a collector.
Pricing and limits
A cached read costs 1 credit and credits are prepaid, so an integration stops with a 402 or 429 rather than running up a bill. The free tier needs no card. See pricing and rate limits and credits.
SDKs
- Python: toktik 0.3.1 — PyPI
- Node.js: @toktikhq/sdk-js 0.4.1 — npm
- All SDK documentation · Realtime stream reference · API reference
Frequently asked questions
Is there an official TikTok LIVE API?
Not for LIVE rankings, gifter boards or the agency directory, as far as we know: TikTok does not publish them as a public API. Toktik's Developer API is an independent service that serves the public LIVE data Toktik observes, each response carrying the time and source it was observed. It is not affiliated with TikTok.
Is the TikTok LIVE API free?
There is a free tier with no card: cached reads only, 5,000 requests per day and 150,000 credits per month, with masked leaderboards. Paid tiers raise the limits and unlock history and exports; credits are prepaid and the API stops with a 402 or 429 instead of billing overage.
How do I get an API key?
Sign in, open the Developer area and create a key. Keys are scoped (for example rank:read for rankings, gifter:read for gifter boards) and sent as a Bearer token. The quickstart walks through minting one and making the first call.
Which languages can I use?
Any language that can make HTTPS requests, plus official SDKs: @toktikhq/sdk-js 0.4.1 for JavaScript and TypeScript on npm and toktik 0.3.1 for Python on PyPI. Both cover the REST surface and the realtime stream.
Can I get realtime TikTok LIVE events such as gifts?
Yes. Open a WebSocket stream for the creators you follow and receive decoded events such as gifts, joins and battle updates as they are observed. The SDKs mint and refresh the handshake token and resume subscriptions for you; realtime usage is metered per room-minute.
Toktik is independent and not affiliated with TikTok. The API serves public data Toktik observes; coverage is stated on the methodology page.