Last updated
Rankings
Official leaderboards per board, region and period.
Every operation authenticates with an API key (Authorization: Bearer <key>) and errors use the shared envelope described in Errors. Generated from the API’s OpenAPI document.
Get a board's daily bar
/v1/rankings/day-barsFor each board day of the last days days: how many creators the board listed, the lowest score on it (the bar to make the board) and the top score, read from the last complete board RoomScope observed before the daily reset, and how many complete boards it read that day. daily and the league boards (league_a1 to league_d5).
Query parameters
| Name | Type | Description |
|---|---|---|
regionOptional | string | Region code. Default: VN |
boardOptional | string | daily or a league board.Default: daily |
daysOptional | integer | Days back. Range …–90. Default: 30 |
Request
curl "https://api.next.toktokdata.live/v1/rankings/day-bars" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "data": { "region": "VN", "board": "daily", "days": [ { "boardDay": "2026-11-06", "dayEnd": "2026-11-06T17:00:00.000Z", "leagueClass": null, "entryCount": 99, "minScore": 23150, "maxScore": 880338, "boardCount": 12 } ] }, "provenance": { "observedAt": "2026-11-07T09:00:00.000Z", "freshness": "near_realtime", "source": "tiktok_observed_rank_board", "sourceKind": "official", "coverageStatus": "observed", "methodologyVersion": "board-day-bar-v1", "window": { "from": "2026-10-09", "to": "2026-11-07", "label": "30d" } }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
List past periods of a board
/v1/rankings/historyCompleted periods of one board, newest first, within the plan's history window.
Query parameters
| Name | Type | Description |
|---|---|---|
boardRequired | string | Board key: daily, hourly, popular_live, gaming_daily, gaming_weekly, shopping_daily, shopping_weekly (needs shop:read), or a league board league_a1 … league_d5. |
regionOptional | string | ISO 3166-1 alpha-2 region code. Default: VN |
cursorOptional | string | Opaque cursor from nextCursor of the previous page. |
limitOptional | integer | Periods per page. Range 1–24. Default: 24 |
leagueTierOptional | string | League tier filter, A1 … D5. |
Request
curl "https://api.next.toktokdata.live/v1/rankings/history?board=daily" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "data": { "board": "daily", "region": "VN", "periods": [ { "periodKey": "2026-10-31", "observedAt": "2026-11-01T10:46:44.935Z", "coverageStatus": "observed", "publishable": true, "entries": [ { "rank": 1, "creatorUid": "990000000000000001", "uniqueId": "linh.live", "nickname": "Linh Live", "avatarUrl": null, "isLive": false, "roomId": null, "score": 99000, "leagueClass": null, "leagueClassSource": null, "leagueClassAsOf": null, "movement": "same", "previousRank": null, "masked": false, "unmaskTier": null }, { "rank": 2, "creatorUid": "990000000000000102", "uniqueId": "creator.02", "nickname": "Creator 02", "avatarUrl": null, "isLive": false, "roomId": null, "score": 98000, "leagueClass": null, "leagueClassSource": null, "leagueClassAsOf": null, "movement": "same", "previousRank": null, "masked": false, "unmaskTier": null } ] } ], "nextCursor": null, "hasMore": false, "historyWindowDays": 365, "historyTruncated": false }, "provenance": { "observedAt": "2026-11-01T10:46:44.935Z", "freshness": "historical", "source": "tiktok_observed_rank_board", "sourceKind": "official", "coverageStatus": "observed", "methodologyVersion": "rankings-official-v1", "window": null }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Get a masked row's LIVE totals
/v1/rankings/masked/{ref}LIVE totals of a masked board row over 30 days, by the maskedRef the board returned: sessions, seconds live and average peak viewers. Never the creator's identity, nor a per-day or per-session series that could be matched to a named row. A ref only works for the workspace that received it, and each board read mints new refs.
Path parameters
| Name | Type | Description |
|---|---|---|
refRequired | string | maskedRef of a masked board row. |
Request
curl "https://api.next.toktokdata.live/v1/rankings/masked/ref" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "data": { "sessionsSummary": { "sessions": 6, "liveSeconds": 31400, "averagePeakViewers": 1640 } }, "provenance": { "observedAt": "2026-11-02T13:05:11.000Z", "freshness": "historical", "source": "creator_analytics", "sourceKind": "derived", "coverageStatus": "partial", "methodologyVersion": "masked-creator-v3", "window": { "from": "2026-10-04T08:00:00.000Z", "to": "2026-11-03T08:00:00.000Z", "label": "30d" } }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Get an official board
/v1/rankings/officialOne board for one region, as TikTok publishes it. Boards are reproduced only after coverage passes a gate: read publishable and coverage before showing entries. Entries beyond what the plan unmasks keep rank and score but come back with masked: true, no identity (creatorUid, avatarUrl and roomId are null) and the unmaskTier that reveals them; maskedRef reads their LIVE totals through /v1/rankings/masked/{ref}. A masked entry also has null movement, previousRank and sparkline, which would tell where it sat before. On the current period every other entry carries sparkline: its score in each of the last seven complete periods, oldest first, null where it was not on the board.
Query parameters
| Name | Type | Description |
|---|---|---|
boardRequired | string | Board key: daily, hourly, popular_live, gaming_daily, gaming_weekly, shopping_daily, shopping_weekly (needs shop:read), or a league board league_a1 … league_d5. |
regionOptional | string | ISO 3166-1 alpha-2 region code. Default: VN |
periodOptional | "current" | "history" | current is the running period, history the last completed one.Default: current |
limitOptional | integer | Maximum entries. Range 1–200. Default: 200 |
liveOnlyOptional | "true" | "false" | Only creators live right now. Default: false |
leagueTierOptional | string | League tier filter, A1 … D5. |
Request
curl "https://api.next.toktokdata.live/v1/rankings/official?board=daily" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "data": { "board": { "kind": "official", "board": "daily", "region": "VN", "periodKey": "2026-10-31", "resetAt": null, "publishable": true, "coverage": { "completeBoards": 1, "expectedBoards": 22, "ratio": 0.045454545454545456, "threshold": 0.8 }, "entries": [ { "rank": 1, "creatorUid": "990000000000000001", "uniqueId": "linh.live", "nickname": "Linh Live", "avatarUrl": null, "isLive": true, "roomId": "7990000000000000001", "score": 99000, "leagueClass": null, "leagueClassSource": null, "leagueClassAsOf": null, "movement": "new", "previousRank": null, "masked": false, "unmaskTier": null, "sparkline": [ null, 812000, 846500, 901200, 955000, 1010300, 99000 ] }, { "rank": 2, "creatorUid": "990000000000000102", "uniqueId": "creator.02", "nickname": "Creator 02", "avatarUrl": null, "isLive": false, "roomId": null, "score": 98000, "leagueClass": null, "leagueClassSource": null, "leagueClassAsOf": null, "movement": "new", "previousRank": null, "masked": false, "unmaskTier": null, "sparkline": [ null, 803880, 838035, 892188, 945450, 1000197, 97020 ] } ] } }, "provenance": { "observedAt": "2026-11-01T10:46:44.935Z", "freshness": "historical", "source": "tiktok_observed_rank_board", "sourceKind": "official", "coverageStatus": "observed", "methodologyVersion": "rankings-official-v1", "window": { "from": null, "to": null, "label": "daily" } }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
List covered regions
/v1/rankings/regionsRegions that currently have observed boards, with a display label. Cache it for a day.
Request
curl "https://api.next.toktokdata.live/v1/rankings/regions" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "data": { "regions": [ { "region": "VN", "label": "VN · Vietnam", "coverage": { "completeBoards": 1, "expectedBoards": 22, "ratio": 0.045454545454545456, "threshold": 0.8 }, "boards": [ "daily" ], "notOfferedBoards": [] } ] }, "provenance": { "observedAt": "2026-11-01T10:46:44.935Z", "freshness": "historical", "source": "tiktok_observed_rank_board", "sourceKind": "official", "coverageStatus": "observed", "methodologyVersion": "rankings-official-v1", "window": null }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.