Última atualização
LIVE
Sessões LIVE gravadas, desempenho por criador, a fonte de vídeo LIVE e o chat LIVE recente.
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.
Listar presenteadores
/v1/giftersQuem envia presentes nas salas LIVE que a RoomScope registrou nos últimos 7 ou 30 dias, por diamantes: quantidade de presentes, sessões, criadores presenteados, o criador da última sala e os diamantes do período anterior. Cada presenteador tem um segmento: whale (pelo menos 10.000 diamantes em 7 dias ou 30.000 em 30 dias), rising (pelo menos 1.000 diamantes e o dobro do período anterior), regular (3 sessões ou mais), one_time (uma sessão) ou occasional. region mantém apenas os presentes para criadores dessa região. A cobertura é sempre partial. Exige o plano Pro ou superior.
Parâmetros de query
| Name | Type | Description |
|---|---|---|
windowOptional | "7d" | "30d" | 7d ou 30d.Default: 7d |
segmentOptional | "whale" | "rising" | "regular" | "one_time" | "occasional" | Apenas um segmento. |
regionOptional | string | Região dos criadores presenteados (ex.: VN). |
limitOptional | integer | Número máximo de linhas. Faixa …–500. Default: 50 |
Requisição
curl "https://api.next.toktokdata.live/v1/gifters" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Resposta
{ "data": { "window": "7d", "region": "VN", "segment": null, "counts": { "whale": 1, "rising": 0, "regular": 0, "one_time": 0, "occasional": 0, "total": 1 }, "gifters": [ { "gifterUserId": "6987001122334455667", "gifterUniqueId": "minh.fan", "gifterNickname": "Minh", "avatarUrl": null, "diamondTotal": 18450, "previousDiamondTotal": 9200, "giftCount": 312, "sessions": 4, "creatorsGifted": 2, "lastGiftAt": "2026-11-02T15:41:07.512Z", "lastRoomCreator": "linh.live", "segment": "whale" } ] }, "provenance": { "observedAt": "2026-11-02T15:41:07.512Z", "freshness": "historical", "source": "platform_observed_gifter_events", "sourceKind": "derived", "coverageStatus": "partial", "methodologyVersion": "gifters-observed-v1", "window": { "from": "2026-10-27T04:00:00.000Z", "to": "2026-11-03T04:00:00.000Z", "label": "7d" } }}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 presentes
/v1/giftsOs presentes do TikTok vistos nas salas LIVE que a RoomScope registrou, com as moedas de um presente, as regiões em que foram enviados e quando foram vistos pela primeira e pela última vez. isGlobal é true quando um presente foi visto em pelo menos 3 regiões. Imagens e presentes que ninguém enviou ainda não estão incluídos, por isso a cobertura é partial. Sincronizado diariamente.
Parâmetros de query
| Name | Type | Description |
|---|---|---|
qOptional | string | Parte do nome do presente. |
minCoinsOptional | integer | Mínimo de moedas de um presente. |
maxCoinsOptional | integer | Máximo de moedas de um presente. |
regionOptional | string | Somente presentes vistos nesta região (ex.: VN). |
sortOptional | "coins" | "name" | "recent" | coins (mais moedas primeiro), name ou recent.Default: coins |
limitOptional | integer | Número máximo de linhas. Faixa …–500. Default: 100 |
Requisição
curl "https://api.next.toktokdata.live/v1/gifts" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Resposta
{ "data": { "gifts": [ { "giftId": "5655", "name": "Rose", "coins": 1, "imageUrl": null, "isGlobal": false, "regions": [ "VN" ], "firstSeenAt": "2026-11-01T02:14:09.000Z", "lastSeenAt": "2026-11-07T08:41:52.000Z" } ], "total": 1 }, "provenance": { "observedAt": "2026-11-07T03:10:00.000Z", "freshness": "near_realtime", "source": "platform_observed_live_stream", "sourceKind": "derived", "coverageStatus": "partial", "methodologyVersion": "gift-catalog-observed-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 o chat LIVE recente de um criador
/v1/live/creators/{uid}/commentsOs comentários mais recentes do chat da sala LIVE do criador, os mais antigos primeiro, para um painel de chat ao lado do player. Consulte a cada poucos segundos e passe o cursor da resposta anterior como after para receber só comentários mais novos (no máximo 100 por resposta; se chegaram mais, os 100 mais recentes). Só há comentários de salas que o RoomScope acompanha e que o seu workspace segue (watchlist ou inscrição na sala): status: tracked com roomId; caso contrário, status: not_tracked sem itens (followed diz se o seu workspace segue o criador). O RoomScope guarda os últimos 200 comentários de uma sala por 10 minutos após o último. Grátis (sem créditos), limitado a 60 requisições por minuto por usuário (429 com Retry-After acima disso).
Parâmetros de caminho
| Name | Type | Description |
|---|---|---|
uidRequired | string | Nome de usuário do criador (linh.live); um @ no início é ignorado. |
Parâmetros de query
| Name | Type | Description |
|---|---|---|
afterOptional | string | cursor da resposta anterior: só comentários mais novos. |
Requisição
curl "https://api.next.toktokdata.live/v1/live/creators/linh.live/comments" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Resposta
{ "status": "tracked", "followed": true, "roomId": "7665709659185105682", "items": [ { "id": "7568123456789012345", "createdAt": "2026-11-06T13:05:41.512Z", "comment": "hello from Hanoi!", "user": { "uniqueId": "minh.fan", "nickname": "Minh", "avatarUrl": "https://p16-sign-sg.tiktokcdn.com/avatar-minh.jpeg" } }, { "id": "7568123456789012399", "createdAt": "2026-11-06T13:05:43.208Z", "comment": "sing the last song again please", "user": { "uniqueId": "an.nguyen", "nickname": "An", "avatarUrl": null } } ], "cursor": "1793970343251-0", "provenance": { "observedAt": "2026-11-06T13:05:43.251Z", "freshness": "near_realtime", "source": "platform_observed_live_stream", "sourceKind": "derived", "coverageStatus": "partial", "methodologyVersion": "live-history-v1", "window": null }}Erros
400Parâmetro ou corpo inválido;codeindica o problema.401Chave de API ausente ou desconhecida.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.503Indisponível temporariamente; tente de novo após oRetry-Afterquandoretryablefor true.
Obter o desempenho de LIVE de um criador
/v1/live/creators/{uid}/performanceUma linha por sessão registrada: duração, espectadores de pico, presentes, diamantes e presenteadores distintos. Só para um criador da lista de acompanhamento do workspace ou uma sala que seus membros acompanham; caso contrário, items vem vazio e followed é false.
Parâmetros de caminho
| Name | Type | Description |
|---|---|---|
uidRequired | string | Nome de usuário do criador sem @ (linh.live) ou ID numérico de usuário do TikTok. |
Parâmetros de query
| Name | Type | Description |
|---|---|---|
cursorOptional | string | Cursor opaco obtido do nextCursor da página anterior. |
limitOptional | integer | Linhas por página. Faixa 1–100. Default: 50 |
Requisição
curl "https://api.next.toktokdata.live/v1/live/creators/linh.live/performance" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Resposta
{ "data": { "items": [ { "sessionId": "f18eaa3e-a762-543d-9ea5-178271dc43f9", "sessionStartedAt": "2026-11-01T07:51:44.935Z", "creatorUniqueId": "linh.live", "roomKey": "room:linh.live", "durationSeconds": 7200, "peakViewerCount": 2000, "eventCount": 1000, "chatCount": 600, "giftCount": 80, "totalGiftDiamonds": 5000, "distinctGifterCount": 2 }, { "sessionId": "278f3a86-af07-5768-85d2-6dfff8efee7d", "sessionStartedAt": "2026-10-31T07:51:44.935Z", "creatorUniqueId": "linh.live", "roomKey": "room:linh.live", "durationSeconds": 7200, "peakViewerCount": 1000, "eventCount": 500, "chatCount": 300, "giftCount": 40, "totalGiftDiamonds": 2500, "distinctGifterCount": 2 } ], "nextCursor": null, "historyWindowDays": 365, "historyTruncated": false, "followed": true }, "provenance": { "observedAt": "2026-11-01T07:51:44.935Z", "freshness": "historical", "source": "platform_observed_live_stream", "sourceKind": "derived", "coverageStatus": "observed", "methodologyVersion": "live-history-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 a fonte de vídeo da LIVE de um criador
/v1/live/creators/{uid}/playbackA URL de vídeo assinada e temporária da sala LIVE atual do criador. Seu player a carrega diretamente da CDN do TikTok (source: tiktok-cdn); a RoomScope nunca faz proxy do vídeo. Prefira hlsUrl; flvUrl é a fonte das salas que só oferecem FLV (reproduza com um motor MSE como o mpegts.js); com status: live, pelo menos uma das duas vem preenchida, e expiresAt indica quando essa URL deixa de funcionar. renditions costuma vir vazio. avatarUrl, followerCount e region são null quando desconhecidos. Outras respostas: status: offline (não está ao vivo), status: no_playback (ao vivo, mas o TikTok não expõe uma fonte reproduzível), 202 status: resolving (consulte a mesma URL de novo após o Retry-After), 503 collection_saturated ou live_playback_upstream_unavailable (tente de novo) e 503 live_playback_not_configured enquanto o recurso estiver desativado nesta implantação (não tente de novo). Exige o escopo live:stream, não live:read.
Parâmetros de caminho
| Name | Type | Description |
|---|---|---|
uidRequired | string | Nome de usuário do criador (linh.live); um @ no início é ignorado. |
Requisição
curl "https://api.next.toktokdata.live/v1/live/creators/linh.live/playback" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Resposta
{ "status": "live", "roomId": "7665709659185105682", "title": "Friday night karaoke", "nickname": "Linh", "hlsUrl": "https://pull-hls-l1-sg01.tiktokcdn.com/stage/stream-7665709727191485202_hd/index.m3u8?expire=1786024940&sign=ea92cabbf90993d50a0e3d50ee9ed526", "flvUrl": "https://pull-flv-l1-sg01.tiktokcdn.com/stage/stream-7665709727191485202_hd.flv?expire=1786024940&sign=ea92cabbf90993d50a0e3d50ee9ed526", "expiresAt": "2026-08-06T14:02:20.000Z", "startedAt": "2026-07-23T09:46:40.000Z", "renditions": [], "avatarUrl": "https://p16-sign-sg.tiktokcdn.com/avatar.jpeg", "verified": true, "followerCount": 894314, "region": "VN", "source": "tiktok-cdn", "cached": false}Erros
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.503Indisponível temporariamente; tente de novo após oRetry-Afterquandoretryablefor true.
Enfileirar uma atualização do status ao vivo
/v1/live/creators/{uid}/refreshPede aos workers que verifiquem agora se o criador está ao vivo. Cobrado pela tarifa de atualização.
Parâmetros de caminho
| Name | Type | Description |
|---|---|---|
uidRequired | string | Nome de usuário do criador sem @ (linh.live) ou ID numérico de usuário do TikTok. |
Requisição
curl -X POST "https://api.next.toktokdata.live/v1/live/creators/linh.live/refresh" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Resposta
{ "queued": true, "jobId": "1761994604935-0"}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 sessões de LIVE registradas
/v1/live/sessionsSessões que o RoomScope registrou para os criadores da lista de acompanhamento do workspace e as salas que seus membros acompanham, da mais recente para a mais antiga; sessões de outros workspaces nunca aparecem. Uma sessão ainda em andamento tem endedAt: null.
Parâmetros de query
| Name | Type | Description |
|---|---|---|
creatorUniqueIdOptional | string | Somente as sessões deste criador (nome de usuário sem @). |
cursorOptional | string | Cursor opaco obtido do nextCursor da página anterior. |
limitOptional | integer | Sessões por página. Faixa 1–100. Default: 50 |
Requisição
curl "https://api.next.toktokdata.live/v1/live/sessions" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Resposta
{ "data": { "items": [ { "id": "f18eaa3e-a762-543d-9ea5-178271dc43f9", "roomKey": "room:linh.live", "roomId": "7990000000000000001", "creatorUniqueId": "linh.live", "creatorAvatarUrl": null, "startedAt": "2026-11-01T07:51:44.935Z", "endedAt": "2026-11-01T09:51:44.935Z", "peakViewerCount": 2000, "eventCount": 1000, "chatCount": 600, "giftCount": 80, "totalGiftDiamonds": 5000, "durationSeconds": 7200 }, { "id": "278f3a86-af07-5768-85d2-6dfff8efee7d", "roomKey": "room:linh.live", "roomId": "7990000000000000001", "creatorUniqueId": "linh.live", "creatorAvatarUrl": null, "startedAt": "2026-10-31T07:51:44.935Z", "endedAt": "2026-10-31T09:51:44.935Z", "peakViewerCount": 1000, "eventCount": 500, "chatCount": 300, "giftCount": 40, "totalGiftDiamonds": 2500, "durationSeconds": 7200 } ], "nextCursor": null, "historyWindowDays": 365, "historyTruncated": false }, "provenance": { "observedAt": "2026-11-01T09:51:44.935Z", "freshness": "historical", "source": "platform_observed_live_stream", "sourceKind": "derived", "coverageStatus": "observed", "methodologyVersion": "live-history-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 uma sessão de LIVE
/v1/live/sessions/{session_id}Uma sessão com os totais de presentes e de presenteadores. A sessão de um criador ou sala que o workspace não acompanha responde 404.
Parâmetros de caminho
| Name | Type | Description |
|---|---|---|
session_idRequired | string | ID da sessão, obtido na listagem. |
Requisição
curl "https://api.next.toktokdata.live/v1/live/sessions/f18eaa3e-a762-543d-9ea5-178271dc43f9" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Resposta
{ "data": { "id": "278f3a86-af07-5768-85d2-6dfff8efee7d", "roomKey": "room:linh.live", "roomId": "7990000000000000001", "creatorUniqueId": "linh.live", "creatorAvatarUrl": null, "startedAt": "2026-10-31T07:51:44.935Z", "endedAt": "2026-10-31T09:51:44.935Z", "peakViewerCount": 1000, "eventCount": 500, "chatCount": 300, "giftCount": 40, "totalGiftDiamonds": 2500, "durationSeconds": 7200, "giftRollups": [ { "giftId": "5269", "giftName": "TikTok", "giftType": 1, "giftCount": 10, "diamondTotal": 2470, "senderCount": 2 }, { "giftId": "5655", "giftName": "Rose", "giftType": 1, "giftCount": 30, "diamondTotal": 30, "senderCount": 2 } ], "gifterRollups": [ { "gifterUserId": "991000000000000001", "gifterUniqueId": "gifter.1", "gifterNickname": "Gifter 1", "giftCount": 20, "diamondTotal": 1500 }, { "gifterUserId": "991000000000000002", "gifterUniqueId": "gifter.2", "gifterNickname": "Gifter 2", "giftCount": 20, "diamondTotal": 1000 } ] }, "provenance": { "observedAt": "2026-10-31T09:51:44.935Z", "freshness": "stale", "source": "platform_observed_live_stream", "sourceKind": "derived", "coverageStatus": "stale", "methodologyVersion": "live-history-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 uma sessão LIVE minuto a minuto
/v1/live/sessions/{session_id}/timelineA série por minuto da sessão desde o início: pico de espectadores, eventos, chats, curtidas, presentes, diamantes, novos gifters e baús por minuto, com offsetMinutes desde o início. Só salas gravadas; uma sessão gravada antes de a série existir não tem minutos (coverageStatus: not-covered). Mesma visibilidade da própria sessão.
Parâmetros de caminho
| Name | Type | Description |
|---|---|---|
session_idRequired | string | ID da sessão, obtido na listagem. |
Requisição
curl "https://api.next.toktokdata.live/v1/live/sessions/f18eaa3e-a762-543d-9ea5-178271dc43f9/timeline" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Resposta
{ "data": { "sessionId": "5b9f0c2e-7a51-5d3c-9b0e-1f2a3c4d5e6f", "creatorUniqueId": "linh.live", "startedAt": "2026-11-06T12:00:04.211Z", "endedAt": "2026-11-06T14:00:12.903Z", "durationSeconds": 7208, "peakViewerCount": 1240, "totalGiftDiamonds": 18450, "minutes": [ { "minuteAt": "2026-11-06T12:00:00.000Z", "offsetMinutes": 0, "viewersMax": 800, "events": 120, "chats": 60, "likes": 300, "gifts": 4, "diamonds": 40, "newGifters": 1, "envelopes": 0 }, { "minuteAt": "2026-11-06T12:01:00.000Z", "offsetMinutes": 1, "viewersMax": 840, "events": 130, "chats": 65, "likes": 320, "gifts": 5, "diamonds": 55, "newGifters": 2, "envelopes": 0 }, { "minuteAt": "2026-11-06T12:02:00.000Z", "offsetMinutes": 2, "viewersMax": 880, "events": 140, "chats": 70, "likes": 340, "gifts": 6, "diamonds": 70, "newGifters": 1, "envelopes": 1 } ] }, "provenance": { "observedAt": "2026-10-31T09:51:44.935Z", "freshness": "stale", "source": "platform_observed_live_stream", "sourceKind": "derived", "coverageStatus": "stale", "methodologyVersion": "live-history-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.
Comparar sessões LIVE
/v1/live/sessions/compareDe duas a quatro sessões lado a lado, cada uma com seus totais e seus minutos alinhados em offsetMinutes desde o próprio início. Qualquer sessão que o workspace não segue responde 404.
Parâmetros de query
| Name | Type | Description |
|---|---|---|
idsRequired | string | Ids de sessão separados por vírgula, de 2 a 4. |
Requisição
curl "https://api.next.toktokdata.live/v1/live/sessions/compare?ids=value" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Resposta
{ "data": { "sessions": [ { "sessionId": "5b9f0c2e-7a51-5d3c-9b0e-1f2a3c4d5e6f", "creatorUniqueId": "linh.live", "startedAt": "2026-11-06T12:00:04.211Z", "endedAt": "2026-11-06T14:00:12.903Z", "durationSeconds": 7208, "peakViewerCount": 1240, "totalGiftDiamonds": 18450, "minutes": [ { "minuteAt": "2026-11-06T12:00:00.000Z", "offsetMinutes": 0, "viewersMax": 800, "events": 120, "chats": 60, "likes": 300, "gifts": 4, "diamonds": 40, "newGifters": 1, "envelopes": 0 }, { "minuteAt": "2026-11-06T12:01:00.000Z", "offsetMinutes": 1, "viewersMax": 840, "events": 130, "chats": 65, "likes": 320, "gifts": 5, "diamonds": 55, "newGifters": 2, "envelopes": 0 }, { "minuteAt": "2026-11-06T12:02:00.000Z", "offsetMinutes": 2, "viewersMax": 880, "events": 140, "chats": 70, "likes": 340, "gifts": 6, "diamonds": 70, "newGifters": 1, "envelopes": 1 } ] }, { "sessionId": "8c1d2e3f-4a5b-5c6d-8e7f-9a0b1c2d3e4f", "creatorUniqueId": "linh.live", "startedAt": "2026-11-05T12:01:10.000Z", "endedAt": "2026-11-05T13:30:40.000Z", "durationSeconds": 5370, "peakViewerCount": 980, "totalGiftDiamonds": 9200, "minutes": [ { "minuteAt": "2026-11-06T12:00:00.000Z", "offsetMinutes": 0, "viewersMax": 800, "events": 120, "chats": 60, "likes": 300, "gifts": 4, "diamonds": 80, "newGifters": 1, "envelopes": 0 }, { "minuteAt": "2026-11-06T12:01:00.000Z", "offsetMinutes": 1, "viewersMax": 880, "events": 130, "chats": 65, "likes": 320, "gifts": 5, "diamonds": 110, "newGifters": 2, "envelopes": 0 } ] } ] }, "provenance": { "observedAt": "2026-10-31T09:51:44.935Z", "freshness": "stale", "source": "platform_observed_live_stream", "sourceKind": "derived", "coverageStatus": "stale", "methodologyVersion": "live-history-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.