RoomScope

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

Bảng xếp hạng

Bảng xếp hạng chính thức theo bảng, khu vực và kỳ.

Mọi thao tác đều xác thực bằng API key (Authorization: Bearer <key>) và lỗi dùng chung envelope được mô tả trong Lỗi. Được tạo từ tài liệu OpenAPI của API.

Lấy ngưỡng hằng ngày của một bảng

GET/v1/rankings/day-bars

Với mỗi ngày bảng trong days ngày gần nhất: số creator bảng liệt kê, điểm thấp nhất trên bảng (ngưỡng để lọt vào bảng) và điểm cao nhất, đọc từ bảng hoàn chỉnh cuối cùng RoomScope quan sát được trước khi bảng reset hằng ngày, cùng số bảng hoàn chỉnh đã đọc trong ngày đó. Áp dụng cho daily và các bảng league (league_a1 đến league_d5).

Scoperank:readCreditĐọc dữ liệu cache

Tham số query

Tham số query · GET /v1/rankings/day-bars
NameTypeDescription
regionOptional
stringMã khu vực.
Default: VN
boardOptional
stringdaily hoặc một bảng league.
Default: daily
daysOptional
integerSố ngày lùi lại. Khoảng giá trị …–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"    }  }}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 402 Ví credit của workspace không đủ cho lệnh gọi; resetAt cho biết khi nào credit được reset.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.

Liệt kê các kỳ đã qua của một bảng

GET/v1/rankings/history

Các kỳ đã hoàn tất của một bảng, mới nhất trước, trong khoảng lịch sử của gói.

Scoperank:readCreditĐọc dữ liệu cache

Tham số query

Tham số query · GET /v1/rankings/history
NameTypeDescription
boardRequired
stringKhóa của bảng: daily, hourly, popular_live, gaming_daily, gaming_weekly, shopping_daily, shopping_weekly (cần shop:read), hoặc một bảng league từ league_a1 … league_d5.
regionOptional
stringMã khu vực ISO 3166-1 alpha-2.
Default: VN
cursorOptional
stringCursor mờ lấy từ nextCursor của trang trước.
limitOptional
integerSố kỳ mỗi trang. Khoảng giá trị 1–24.
Default: 24
leagueTierOptional
stringLọc theo hạng league, 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  }}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 402 Ví credit của workspace không đủ cho lệnh gọi; resetAt cho biết khi nào credit được reset.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.

Lấy số tổng LIVE của một hàng bị che

GET/v1/rankings/masked/{ref}

Số tổng LIVE trong 30 ngày của một hàng bị che trên bảng, theo maskedRef mà bảng trả về: số phiên, số giây live và người xem đỉnh trung bình. Không bao giờ có danh tính của creator, cũng không có chuỗi theo ngày hay theo phiên có thể so khớp với một hàng có tên. Một ref chỉ dùng được trong workspace đã nhận nó, và mỗi lần đọc bảng tạo ref mới.

Scoperank:readCreditĐọc dữ liệu cache

Tham số path

Tham số path · GET /v1/rankings/masked/{ref}
NameTypeDescription
refRequired
stringmaskedRef của một hàng bị che trên bảng.

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"    }  }}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 402 Ví credit của workspace không đủ cho lệnh gọi; resetAt cho biết khi nào credit được reset.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.

Lấy một bảng chính thức

GET/v1/rankings/official

Một bảng cho một khu vực, đúng như TikTok công bố. Bảng chỉ được tái hiện sau khi độ phủ vượt qua một ngưỡng: hãy đọc publishable và coverage trước khi hiển thị các entry. Những entry vượt quá phạm vi gói được hiện tên vẫn giữ rank và score nhưng được trả về với masked: true, không có danh tính (creatorUid, avatarUrl và roomId là null), kèm unmaskTier là gói hiện tên chúng; maskedRef đọc số tổng LIVE của chúng qua /v1/rankings/masked/{ref}. Entry bị che cũng có movement, previousRank và sparkline là null, vì chúng sẽ cho biết entry đó từng ở đâu. Ở kỳ hiện tại, mọi entry khác mang sparkline: điểm của nó trong từng kỳ đầy đủ ở bảy kỳ gần nhất, cũ nhất trước, null ở kỳ nó không có mặt trên bảng.

Scoperank:readCreditĐọc dữ liệu cache

Tham số query

Tham số query · GET /v1/rankings/official
NameTypeDescription
boardRequired
stringKhóa của bảng: daily, hourly, popular_live, gaming_daily, gaming_weekly, shopping_daily, shopping_weekly (cần shop:read), hoặc một bảng league từ league_a1 … league_d5.
regionOptional
stringMã khu vực ISO 3166-1 alpha-2.
Default: VN
periodOptional
"current" | "history"current là kỳ đang chạy, history là kỳ gần nhất đã hoàn tất.
Default: current
limitOptional
integerSố entry tối đa. Khoảng giá trị 1–200.
Default: 200
liveOnlyOptional
"true" | "false"Chỉ các creator đang live ngay lúc này.
Default: false
leagueTierOptional
stringLọc theo hạng league, 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"    }  }}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 402 Ví credit của workspace không đủ cho lệnh gọi; resetAt cho biết khi nào credit được reset.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.

Liệt kê các khu vực được phủ

GET/v1/rankings/regions

Các khu vực hiện có bảng đã quan sát, kèm nhãn hiển thị. Hãy cache kết quả trong một ngày.

Scoperank:readCreditĐọc dữ liệu cache

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  }}

Lỗi

  • 400 Tham số hoặc body không hợp lệ; code cho biết vấn đề.
  • 401 API key bị thiếu hoặc không xác định.
  • 402 Ví credit của workspace không đủ cho lệnh gọi; resetAt cho biết khi nào credit được reset.
  • 403 Key thiếu scope, hoặc gói không bao gồm tính năng này.
  • 429 Vượt tốc độ request (theo giây, theo phút hoặc theo ngày); hãy tuân theo Retry-After.
Trang này có hữu ích không?