RoomScope

Cập nhật lần cuối

Rankings

Official leaderboards per board, region and period.

Tài liệu kỹ thuật hiện chỉ có bằng tiếng Anh.

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/history

Completed periods of one board, newest first, within the plan's history window.

Scoperank:readCreditsCached read

Query parameters

Query parameters of GET /v1/rankings/history
NameTypeDescription
boardRequired
stringBoard 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
stringISO 3166-1 alpha-2 region code.
Default: VN
cursorOptional
stringOpaque cursor from nextCursor of the previous page.
limitOptional
integerPeriods per page. Range 1–24.
Default: 24
leagueTierOptional
stringLeague tier filter, A1 … D5.

Request

curl "https://api.toktokdata.live/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",    "sourceKind": "official",    "coverageStatus": "observed",    "methodologyVersion": "rankings-official-v1",    "window": null  }}

Errors

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 402 The workspace's credit wallet cannot cover the call; resetAt says when the credits reset.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded; honour Retry-After.

Get an official board

GET/v1/rankings/official

One 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. On the current period every entry carries sparkline: its score in each of the last seven complete periods, oldest first, null where it was not on the board.

Scoperank:readCreditsCached read

Query parameters

Query parameters of GET /v1/rankings/official
NameTypeDescription
boardRequired
stringBoard 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
stringISO 3166-1 alpha-2 region code.
Default: VN
periodOptional
"current" | "history"current is the running period, history the last completed one.
Default: current
limitOptional
integerMaximum entries. Range 1–200.
Default: 200
liveOnlyOptional
"true" | "false"Only creators live right now.
Default: false
leagueTierOptional
stringLeague tier filter, A1 … D5.

Request

curl "https://api.toktokdata.live/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,          "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

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 402 The workspace's credit wallet cannot cover the call; resetAt says when the credits reset.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded; honour Retry-After.

List covered regions

GET/v1/rankings/regions

Regions that currently have observed boards, with a display label. Cache it for a day.

Scoperank:readCreditsCached read

Request

curl "https://api.toktokdata.live/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",    "sourceKind": "official",    "coverageStatus": "observed",    "methodologyVersion": "rankings-official-v1",    "window": null  }}

Errors

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 402 The workspace's credit wallet cannot cover the call; resetAt says when the credits reset.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded; honour Retry-After.
Trang này có hữu ích không?