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
/v1/rankings/day-barsUntuk 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).
Parameter query
| Name | Type | Description |
|---|---|---|
regionOptional | string | Kode wilayah. Default: VN |
boardOptional | string | daily atau papan liga.Default: daily |
daysOptional | integer | Jumlah 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
{ "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
400Parameter atau body tidak valid;codemenyebutkan masalahnya.401API key tidak ada atau tidak dikenal.402Dompet kredit workspace tidak dapat menutup biaya panggilan ini;resetAtmenunjukkan kapan kredit di-reset.403Key tidak memiliki scope tersebut, atau paket tidak mencakup fitur ini.429Laju permintaan terlampaui (per detik, per menit, atau per hari); patuhiRetry-After.
Daftar periode sebelumnya dari sebuah papan
/v1/rankings/historyPeriode yang sudah selesai dari satu papan, dari yang terbaru, dalam jendela riwayat paket.
Parameter query
| Name | Type | Description |
|---|---|---|
boardRequired | string | Kunci papan: daily, hourly, popular_live, gaming_daily, gaming_weekly, shopping_daily, shopping_weekly (memerlukan shop:read), atau papan liga league_a1 … league_d5. |
regionOptional | string | Kode wilayah ISO 3166-1 alpha-2. Default: VN |
cursorOptional | string | Cursor opaque dari nextCursor halaman sebelumnya. |
limitOptional | integer | Periode per halaman. Rentang 1–24. Default: 24 |
leagueTierOptional | string | Filter tingkat liga, A1 … D5. |
Permintaan
curl "https://api.next.toktokdata.live/v1/rankings/history?board=daily" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Respons
{ "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
400Parameter atau body tidak valid;codemenyebutkan masalahnya.401API key tidak ada atau tidak dikenal.402Dompet kredit workspace tidak dapat menutup biaya panggilan ini;resetAtmenunjukkan kapan kredit di-reset.403Key tidak memiliki scope tersebut, atau paket tidak mencakup fitur ini.429Laju permintaan terlampaui (per detik, per menit, atau per hari); patuhiRetry-After.
Ambil total LIVE dari baris tersamar
/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.
Parameter path
| Name | Type | Description |
|---|---|---|
refRequired | string | maskedRef dari baris papan yang tersamar. |
Permintaan
curl "https://api.next.toktokdata.live/v1/rankings/masked/ref" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Respons
{ "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
400Parameter atau body tidak valid;codemenyebutkan masalahnya.401API key tidak ada atau tidak dikenal.402Dompet kredit workspace tidak dapat menutup biaya panggilan ini;resetAtmenunjukkan kapan kredit di-reset.403Key tidak memiliki scope tersebut, atau paket tidak mencakup fitur ini.429Laju permintaan terlampaui (per detik, per menit, atau per hari); patuhiRetry-After.
Ambil papan resmi
/v1/rankings/officialSatu 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.
Parameter query
| Name | Type | Description |
|---|---|---|
boardRequired | string | Kunci papan: daily, hourly, popular_live, gaming_daily, gaming_weekly, shopping_daily, shopping_weekly (memerlukan shop:read), atau papan liga league_a1 … league_d5. |
regionOptional | string | Kode 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 | integer | Jumlah entri maksimum. Rentang 1–200. Default: 200 |
liveOnlyOptional | "true" | "false" | Hanya kreator yang sedang live saat ini. Default: false |
leagueTierOptional | string | Filter tingkat liga, A1 … D5. |
Permintaan
curl "https://api.next.toktokdata.live/v1/rankings/official?board=daily" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Respons
{ "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
400Parameter atau body tidak valid;codemenyebutkan masalahnya.401API key tidak ada atau tidak dikenal.402Dompet kredit workspace tidak dapat menutup biaya panggilan ini;resetAtmenunjukkan kapan kredit di-reset.403Key tidak memiliki scope tersebut, atau paket tidak mencakup fitur ini.429Laju permintaan terlampaui (per detik, per menit, atau per hari); patuhiRetry-After.
Daftar wilayah yang tercakup
/v1/rankings/regionsWilayah yang saat ini memiliki papan teramati, beserta label tampilan. Simpan di cache selama satu hari.
Permintaan
curl "https://api.next.toktokdata.live/v1/rankings/regions" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Respons
{ "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
400Parameter atau body tidak valid;codemenyebutkan masalahnya.401API key tidak ada atau tidak dikenal.402Dompet kredit workspace tidak dapat menutup biaya panggilan ini;resetAtmenunjukkan kapan kredit di-reset.403Key tidak memiliki scope tersebut, atau paket tidak mencakup fitur ini.429Laju permintaan terlampaui (per detik, per menit, atau per hari); patuhiRetry-After.