Última atualização
Rankings
Rankings oficiais por tipo de ranking, região e período.
Toda operação se autentica com uma chave de API (Authorization: Bearer <key>) e os erros usam o envelope comum descrito em Erros. Gerado a partir do documento OpenAPI da API.
Obter a nota de corte diária de um ranking
/v1/rankings/day-barsPara cada dia de ranking dos últimos days dias: quantos criadores o ranking listou, a menor pontuação nele (a nota de corte para entrar no ranking) e a maior, lidas do último ranking completo que o RoomScope observou antes do reinício diário, e quantos rankings completos ele leu naquele dia. daily e os rankings de liga (de league_a1 a league_d5).
Parâmetros de query
| Name | Type | Description |
|---|---|---|
regionOptional | string | Código da região. Default: VN |
boardOptional | string | daily ou um ranking de liga.Default: daily |
daysOptional | integer | Dias para trás. Faixa …–90. Default: 30 |
Requisição
curl "https://api.next.toktokdata.live/v1/rankings/day-bars" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Resposta
{ "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" } }}Erros
400Parâmetro ou corpo inválido;codeindica o problema.401Chave de API ausente ou desconhecida.402A carteira de créditos do espaço de trabalho não cobre a chamada;resetAtindica quando os créditos são renovados.403A chave não tem o escopo, ou o plano não inclui o recurso.429Ritmo de requisições excedido (por segundo, por minuto ou por dia); respeiteRetry-After.
Listar períodos anteriores de um ranking
/v1/rankings/historyPeríodos concluídos de um ranking, do mais recente ao mais antigo, dentro da janela de histórico do plano.
Parâmetros de query
| Name | Type | Description |
|---|---|---|
boardRequired | string | Chave do ranking: daily, hourly, popular_live, gaming_daily, gaming_weekly, shopping_daily, shopping_weekly (exige shop:read) ou um ranking de liga, de league_a1 a league_d5. |
regionOptional | string | Código de região ISO 3166-1 alpha-2. Default: VN |
cursorOptional | string | Cursor opaco obtido do nextCursor da página anterior. |
limitOptional | integer | Períodos por página. Faixa 1–24. Default: 24 |
leagueTierOptional | string | Filtro por divisão da liga, de A1 a D5. |
Requisição
curl "https://api.next.toktokdata.live/v1/rankings/history?board=daily" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Resposta
{ "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 }}Erros
400Parâmetro ou corpo inválido;codeindica o problema.401Chave de API ausente ou desconhecida.402A carteira de créditos do espaço de trabalho não cobre a chamada;resetAtindica quando os créditos são renovados.403A chave não tem o escopo, ou o plano não inclui o recurso.429Ritmo de requisições excedido (por segundo, por minuto ou por dia); respeiteRetry-After.
Obter os totais LIVE de uma linha oculta
/v1/rankings/masked/{ref}Totais LIVE de uma linha oculta do ranking nos últimos 30 dias, pelo maskedRef que o ranking retornou: sessões, segundos ao vivo e média de espectadores de pico. Nunca a identidade do criador, nem uma série por dia ou por sessão que possa ser comparada a uma linha com nome. Um ref só funciona no workspace que o recebeu, e cada leitura do ranking gera novos refs.
Parâmetros de caminho
| Name | Type | Description |
|---|---|---|
refRequired | string | maskedRef de uma linha oculta do ranking. |
Requisição
curl "https://api.next.toktokdata.live/v1/rankings/masked/ref" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Resposta
{ "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" } }}Erros
400Parâmetro ou corpo inválido;codeindica o problema.401Chave de API ausente ou desconhecida.402A carteira de créditos do espaço de trabalho não cobre a chamada;resetAtindica quando os créditos são renovados.403A chave não tem o escopo, ou o plano não inclui o recurso.429Ritmo de requisições excedido (por segundo, por minuto ou por dia); respeiteRetry-After.
Obter um ranking oficial
/v1/rankings/officialUm ranking de uma região, como o TikTok o publica. Os rankings só são reproduzidos depois que a cobertura passa por um limite: leia publishable e coverage antes de mostrar as entradas. Entradas além do que o plano revela mantêm rank e score, mas voltam com masked: true, sem identidade (creatorUid, avatarUrl e roomId são null) e com o unmaskTier que as revela; maskedRef lê seus totais LIVE por /v1/rankings/masked/{ref}. Uma entrada oculta também tem movement, previousRank e sparkline null, porque diriam onde ela estava antes. No período atual, cada uma das demais entradas traz sparkline: sua pontuação em cada um dos últimos sete períodos completos, do mais antigo ao mais recente, null onde não estava no ranking.
Parâmetros de query
| Name | Type | Description |
|---|---|---|
boardRequired | string | Chave do ranking: daily, hourly, popular_live, gaming_daily, gaming_weekly, shopping_daily, shopping_weekly (exige shop:read) ou um ranking de liga, de league_a1 a league_d5. |
regionOptional | string | Código de região ISO 3166-1 alpha-2. Default: VN |
periodOptional | "current" | "history" | current é o período em andamento; history, o último concluído.Default: current |
limitOptional | integer | Número máximo de entradas. Faixa 1–200. Default: 200 |
liveOnlyOptional | "true" | "false" | Somente criadores ao vivo agora. Default: false |
leagueTierOptional | string | Filtro por divisão da liga, de A1 a D5. |
Requisição
curl "https://api.next.toktokdata.live/v1/rankings/official?board=daily" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Resposta
{ "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" } }}Erros
400Parâmetro ou corpo inválido;codeindica o problema.401Chave de API ausente ou desconhecida.402A carteira de créditos do espaço de trabalho não cobre a chamada;resetAtindica quando os créditos são renovados.403A chave não tem o escopo, ou o plano não inclui o recurso.429Ritmo de requisições excedido (por segundo, por minuto ou por dia); respeiteRetry-After.
Listar regiões cobertas
/v1/rankings/regionsRegiões que têm rankings observados no momento, com um rótulo de exibição. Guarde em cache por um dia.
Requisição
curl "https://api.next.toktokdata.live/v1/rankings/regions" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Resposta
{ "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 }}Erros
400Parâmetro ou corpo inválido;codeindica o problema.401Chave de API ausente ou desconhecida.402A carteira de créditos do espaço de trabalho não cobre a chamada;resetAtindica quando os créditos são renovados.403A chave não tem o escopo, ou o plano não inclui o recurso.429Ritmo de requisições excedido (por segundo, por minuto ou por dia); respeiteRetry-After.