RoomScope

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

GET/v1/rankings/day-bars

For 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).

Scoperank:readCreditsCached read

Query parameters

Query parameters · GET /v1/rankings/day-bars
NameTypeDescription
regionOptional
stringRegion code.
Default: VN
boardOptional
stringdaily or a league board.
Default: daily
daysOptional
integerDays back. Range …–90.
Default: 30

Request

curl "https://api.next.toktokdata.live/v1/rankings/day-bars" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Response

200 OK
{  "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

  • 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 (per second, per minute or per day); honour Retry-After.

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 · 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.next.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 (per second, per minute or per day); honour Retry-After.

Get a masked row's LIVE totals

GET/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.

Scoperank:readCreditsCached read

Path parameters

Path parameters · GET /v1/rankings/masked/{ref}
NameTypeDescription
refRequired
stringmaskedRef of a masked board row.

Request

curl "https://api.next.toktokdata.live/v1/rankings/masked/ref" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Response

200 OK
{  "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

  • 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 (per second, per minute or per day); 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 (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.

Scoperank:readCreditsCached read

Query parameters

Query parameters · 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.next.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 (per second, per minute or per day); 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.next.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 (per second, per minute or per day); honour Retry-After.
Was this page helpful?