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.
List past periods of a board
GET
/v1/rankings/historyCompleted periods of one board, newest first, within the plan's history window.
Scoperank:readCreditsCached read
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.roomscope.io/v1/rankings/history?board=daily" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
200 OK
{ "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", "coverageStatus": "observed", "methodologyVersion": "rankings-official-v1" }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded; honourRetry-After.
Get an official board
GET
/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, and the unmaskTier that reveals them.
Scoperank:readCreditsCached read
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.roomscope.io/v1/rankings/official?board=daily" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
200 OK
{ "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 }, { "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 } ] } }, "provenance": { "observedAt": "2026-11-01T10:46:44.935Z", "freshness": "historical", "source": "tiktok_observed_rank_board", "coverageStatus": "observed", "methodologyVersion": "rankings-official-v1" }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded; honourRetry-After.
List covered regions
GET
/v1/rankings/regionsRegions that currently have observed boards, with a display label. Cache it for a day.
Scoperank:readCreditsCached read
Request
curl "https://api.roomscope.io/v1/rankings/regions" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
200 OK
{ "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", "coverageStatus": "observed", "methodologyVersion": "rankings-official-v1" }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded; honourRetry-After.
Was this page helpful?