Rankings

Get real-time leaderboard data for a live room - top gifters, online audience rankings, and engagement scores. Uses the ‘sign-and-return’ pattern for authenticated data.

GET /webcast/rankings

Returns a signed request for a live room’s gifter ranking (ranklist/online_audience) using the “sign-and-return” pattern: the response gives you a signed_url plus the exact headers to send, and you make the final request yourself.

The live top-viewer / online-audience list is only reliably available over the WebSocket, not this REST route.

TikTok now requires an authenticated, logged-in session for online_audience. As a result:

• Fetching the signed_url with no cookies returns status_code: 20003 (“User doesn’t login”).
• Fetching it with your own TikTok session cookies returns status_code: 10011 (“Request params error”), because your session does not match the signed request.

There is no anonymous way to read online_audience at this time. For the live top-viewer list, use the WebSocket (see below).

Getting the live top-viewer list (recommended)

Connect to the live room over the WebSocket and read the roomUserSeq event. Its topViewers array carries the in-room top viewers alongside the live viewerCount. This is the supported, real-time source and needs no extra signing or cookies.

The rankUpdate event also carries ranked entries (user, rank, score), but TikTok only emits it for rooms that are currently running a ranking event (gifter battles, weekly/regional ranks). A room with no active ranking emits none - this is expected.

Parameters

Parameter	Type	Required	Description
room_id	string	No	TikTok room ID. Required to get a signed request.
unique_id	string	No	TikTok username. If you pass this without room_id, the response is a resolve_required action telling you how to resolve the current room_id first.

Response

With a room_id, the endpoint returns a signed request, not the ranking data itself:

{
  "status_code": 0,
  "signed_url": "https://webcast.tiktok.com/webcast/ranklist/online_audience/?...",
  "method": "GET",
  "headers": { "User-Agent": "...", "Referer": "https://www.tiktok.com/" }
}

You then make that request yourself. As noted in the warning above, TikTok currently returns 20003 / 10011 for online_audience regardless of whether cookies are attached, so use the WebSocket roomUserSeq.topViewers event for the live top-viewer list instead.

Example

cURL

# Step 1: resolve the current room_id (if you only have a username)
curl "https://api.tik.tools/webcast/rankings?unique_id=username&apiKey=YOUR_KEY"

# Step 2: get the signed request for that room
curl "https://api.tik.tools/webcast/rankings?room_id=ROOM_ID&apiKey=YOUR_KEY"