RoomScope

Terakhir diperbarui

Peringkat

Papan peringkat resmi per papan, wilayah, dan periode.

Setiap operasi diautentikasi dengan API key (Authorization: Bearer <key>) dan error memakai amplop bersama yang dijelaskan di Error. Dibuat dari dokumen OpenAPI milik API.

Ambil batas harian sebuah papan

GET/v1/rankings/day-bars

Untuk setiap hari papan dalam days hari terakhir: berapa kreator yang tercantum di papan, skor terendah di papan (batas untuk masuk papan) dan skor tertinggi, dibaca dari papan lengkap terakhir yang diamati RoomScope sebelum reset harian, serta berapa papan lengkap yang dibaca hari itu. daily dan papan liga (league_a1 hingga league_d5).

Scoperank:readKreditBaca cache

Parameter query

Parameter query · GET /v1/rankings/day-bars
NameTypeDescription
regionOptional
stringKode wilayah.
Default: VN
boardOptional
stringdaily atau papan liga.
Default: daily
daysOptional
integerJumlah hari ke belakang. Rentang …–90.
Default: 30

Permintaan

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

Respons

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

Error

  • 400 Parameter atau body tidak valid; code menyebutkan masalahnya.
  • 401 API key tidak ada atau tidak dikenal.
  • 402 Dompet kredit workspace tidak dapat menutup biaya panggilan ini; resetAt menunjukkan kapan kredit di-reset.
  • 403 Key tidak memiliki scope tersebut, atau paket tidak mencakup fitur ini.
  • 429 Laju permintaan terlampaui (per detik, per menit, atau per hari); patuhi Retry-After.

Daftar periode sebelumnya dari sebuah papan

GET/v1/rankings/history

Periode yang sudah selesai dari satu papan, dari yang terbaru, dalam jendela riwayat paket.

Scoperank:readKreditBaca cache

Parameter query

Parameter query · GET /v1/rankings/history
NameTypeDescription
boardRequired
stringKunci papan: daily, hourly, popular_live, gaming_daily, gaming_weekly, shopping_daily, shopping_weekly (memerlukan shop:read), atau papan liga league_a1 … league_d5.
regionOptional
stringKode wilayah ISO 3166-1 alpha-2.
Default: VN
cursorOptional
stringCursor opaque dari nextCursor halaman sebelumnya.
limitOptional
integerPeriode per halaman. Rentang 1–24.
Default: 24
leagueTierOptional
stringFilter tingkat liga, A1 … D5.

Permintaan

curl "https://api.next.toktokdata.live/v1/rankings/history?board=daily" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Respons

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

Error

  • 400 Parameter atau body tidak valid; code menyebutkan masalahnya.
  • 401 API key tidak ada atau tidak dikenal.
  • 402 Dompet kredit workspace tidak dapat menutup biaya panggilan ini; resetAt menunjukkan kapan kredit di-reset.
  • 403 Key tidak memiliki scope tersebut, atau paket tidak mencakup fitur ini.
  • 429 Laju permintaan terlampaui (per detik, per menit, atau per hari); patuhi Retry-After.

Ambil total LIVE dari baris tersamar

GET/v1/rankings/masked/{ref}

Total LIVE 30 hari dari baris papan yang tersamar, berdasarkan maskedRef yang dikembalikan papan: jumlah sesi, detik siaran, dan rata-rata penonton puncak. Tidak pernah berisi identitas kreator, maupun deret per hari atau per sesi yang bisa dicocokkan dengan baris bernama. Sebuah ref hanya berlaku di workspace yang menerimanya, dan setiap pembacaan papan membuat ref baru.

Scoperank:readKreditBaca cache

Parameter path

Parameter path · GET /v1/rankings/masked/{ref}
NameTypeDescription
refRequired
stringmaskedRef dari baris papan yang tersamar.

Permintaan

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

Respons

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

Error

  • 400 Parameter atau body tidak valid; code menyebutkan masalahnya.
  • 401 API key tidak ada atau tidak dikenal.
  • 402 Dompet kredit workspace tidak dapat menutup biaya panggilan ini; resetAt menunjukkan kapan kredit di-reset.
  • 403 Key tidak memiliki scope tersebut, atau paket tidak mencakup fitur ini.
  • 429 Laju permintaan terlampaui (per detik, per menit, atau per hari); patuhi Retry-After.

Ambil papan resmi

GET/v1/rankings/official

Satu papan untuk satu wilayah, sebagaimana TikTok menerbitkannya. Papan hanya direproduksi setelah cakupan melewati ambang: baca publishable dan coverage sebelum menampilkan entri. Entri di luar yang dibuka paket tetap menyimpan rank dan score, tetapi kembali dengan masked: true, tanpa identitas (creatorUid, avatarUrl, dan roomId bernilai null), beserta unmaskTier yang membukanya; maskedRef membaca total LIVE-nya melalui /v1/rankings/masked/{ref}. Entri tersamar juga memiliki movement, previousRank, dan sparkline bernilai null, karena ketiganya akan menunjukkan posisinya sebelumnya. Pada periode saat ini, setiap entri lainnya membawa sparkline: skornya di setiap tujuh periode lengkap terakhir, dari yang terlama, null saat tidak ada di papan.

Scoperank:readKreditBaca cache

Parameter query

Parameter query · GET /v1/rankings/official
NameTypeDescription
boardRequired
stringKunci papan: daily, hourly, popular_live, gaming_daily, gaming_weekly, shopping_daily, shopping_weekly (memerlukan shop:read), atau papan liga league_a1 … league_d5.
regionOptional
stringKode wilayah ISO 3166-1 alpha-2.
Default: VN
periodOptional
"current" | "history"current adalah periode yang sedang berjalan, history adalah periode terakhir yang sudah selesai.
Default: current
limitOptional
integerJumlah entri maksimum. Rentang 1–200.
Default: 200
liveOnlyOptional
"true" | "false"Hanya kreator yang sedang live saat ini.
Default: false
leagueTierOptional
stringFilter tingkat liga, A1 … D5.

Permintaan

curl "https://api.next.toktokdata.live/v1/rankings/official?board=daily" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Respons

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

Error

  • 400 Parameter atau body tidak valid; code menyebutkan masalahnya.
  • 401 API key tidak ada atau tidak dikenal.
  • 402 Dompet kredit workspace tidak dapat menutup biaya panggilan ini; resetAt menunjukkan kapan kredit di-reset.
  • 403 Key tidak memiliki scope tersebut, atau paket tidak mencakup fitur ini.
  • 429 Laju permintaan terlampaui (per detik, per menit, atau per hari); patuhi Retry-After.

Daftar wilayah yang tercakup

GET/v1/rankings/regions

Wilayah yang saat ini memiliki papan teramati, beserta label tampilan. Simpan di cache selama satu hari.

Scoperank:readKreditBaca cache

Permintaan

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

Respons

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

Error

  • 400 Parameter atau body tidak valid; code menyebutkan masalahnya.
  • 401 API key tidak ada atau tidak dikenal.
  • 402 Dompet kredit workspace tidak dapat menutup biaya panggilan ini; resetAt menunjukkan kapan kredit di-reset.
  • 403 Key tidak memiliki scope tersebut, atau paket tidak mencakup fitur ini.
  • 429 Laju permintaan terlampaui (per detik, per menit, atau per hari); patuhi Retry-After.
Apakah halaman ini membantu?