Última actualización
LIVE
Sesiones LIVE grabadas, rendimiento por creador, la fuente de video LIVE y el chat LIVE reciente.
Cada operación se autentica con una clave de API (Authorization: Bearer <key>) y los errores usan el sobre compartido que se describe en Errores. Generado a partir del documento OpenAPI de la API.
Listar donadores
/v1/giftersQuiénes envían regalos en las salas LIVE que registró RoomScope en los últimos 7 o 30 días, por diamantes: cantidad de regalos, sesiones, creadores que recibieron regalos, el creador de la última sala y los diamantes del periodo anterior. Cada donador tiene un segmento: whale (al menos 10.000 diamantes en 7 días o 30.000 en 30 días), rising (al menos 1.000 diamantes y el doble del periodo anterior), regular (3 sesiones o más), one_time (una sesión) o occasional. region conserva solo los regalos a creadores de esa región. La cobertura siempre es partial. Requiere el plan Pro o superior.
Parámetros de consulta
| Name | Type | Description |
|---|---|---|
windowOptional | "7d" | "30d" | 7d o 30d.Default: 7d |
segmentOptional | "whale" | "rising" | "regular" | "one_time" | "occasional" | Solo un segmento. |
regionOptional | string | Región de los creadores que reciben los regalos (p. ej., VN). |
limitOptional | integer | Máximo de filas. Rango …–500. Default: 50 |
Solicitud
curl "https://api.next.toktokdata.live/v1/gifters" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Respuesta
{ "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" } }}Errores
400Parámetro o cuerpo no válido;codeindica el problema.401Clave de API ausente o desconocida.402La billetera de créditos del espacio de trabajo no alcanza para cubrir la llamada;resetAtindica cuándo se reinician los créditos.403La clave no tiene el alcance, o el plan no incluye la función.429Se superó el ritmo de solicitudes (por segundo, por minuto o por día); respetaRetry-After.
Listar regalos
/v1/giftsLos regalos de TikTok vistos en las salas LIVE que registró RoomScope, con las monedas de un regalo, las regiones en las que se enviaron y cuándo se vieron por primera y última vez. isGlobal es true cuando un regalo se vio en al menos 3 regiones. No se incluyen las imágenes ni los regalos que nadie ha enviado todavía, por lo que la cobertura es partial. Se sincroniza a diario.
Parámetros de consulta
| Name | Type | Description |
|---|---|---|
qOptional | string | Parte del nombre del regalo. |
minCoinsOptional | integer | Monedas mínimas de un regalo. |
maxCoinsOptional | integer | Monedas máximas de un regalo. |
regionOptional | string | Solo los regalos vistos en esta región (p. ej., VN). |
sortOptional | "coins" | "name" | "recent" | coins (más primero), name o recent.Default: coins |
limitOptional | integer | Máximo de filas. Rango …–500. Default: 100 |
Solicitud
curl "https://api.next.toktokdata.live/v1/gifts" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Respuesta
{ "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 }}Errores
400Parámetro o cuerpo no válido;codeindica el problema.401Clave de API ausente o desconocida.402La billetera de créditos del espacio de trabajo no alcanza para cubrir la llamada;resetAtindica cuándo se reinician los créditos.403La clave no tiene el alcance, o el plan no incluye la función.429Se superó el ritmo de solicitudes (por segundo, por minuto o por día); respetaRetry-After.
Obtener el chat LIVE reciente de un creador
/v1/live/creators/{uid}/commentsLos últimos comentarios del chat de la sala LIVE del creador, los más antiguos primero, para un panel de chat junto al reproductor. Consúltalo cada pocos segundos y pasa el cursor de la respuesta anterior como after para recibir solo comentarios más nuevos (como máximo 100 por respuesta; si llegaron más, los 100 más recientes). Solo hay comentarios de salas que RoomScope sigue y que tu workspace sigue (watchlist o suscripción a la sala): status: tracked con roomId; si no, status: not_tracked sin elementos (followed indica si tu workspace sigue al creador). RoomScope guarda los últimos 200 comentarios de una sala durante 10 minutos después del último. Gratis (sin créditos), limitado a 60 solicitudes por minuto por usuario (429 con Retry-After por encima).
Parámetros de ruta
| Name | Type | Description |
|---|---|---|
uidRequired | string | Nombre de usuario del creador (linh.live); se ignora una @ inicial. |
Parámetros de consulta
| Name | Type | Description |
|---|---|---|
afterOptional | string | cursor de la respuesta anterior: solo comentarios más nuevos. |
Solicitud
curl "https://api.next.toktokdata.live/v1/live/creators/linh.live/comments" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Respuesta
{ "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 }}Errores
400Parámetro o cuerpo no válido;codeindica el problema.401Clave de API ausente o desconocida.403La clave no tiene el alcance, o el plan no incluye la función.429Se superó el ritmo de solicitudes (por segundo, por minuto o por día); respetaRetry-After.503No disponible temporalmente; reintenta después deRetry-Aftercuandoretryablesea true.
Obtener el rendimiento en LIVE de un creador
/v1/live/creators/{uid}/performanceUna fila por sesión registrada: duración, espectadores pico, regalos, diamantes y donantes distintos. Solo para un creador de la lista de seguimiento del workspace o una sala que siguen sus miembros; si no, items está vacío y followed es false.
Parámetros de ruta
| Name | Type | Description |
|---|---|---|
uidRequired | string | Nombre de usuario del creador sin @ (linh.live) o ID numérico de usuario de TikTok. |
Parámetros de consulta
| Name | Type | Description |
|---|---|---|
cursorOptional | string | Cursor opaco tomado de nextCursor de la página anterior. |
limitOptional | integer | Filas por página. Rango 1–100. Default: 50 |
Solicitud
curl "https://api.next.toktokdata.live/v1/live/creators/linh.live/performance" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Respuesta
{ "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 }}Errores
400Parámetro o cuerpo no válido;codeindica el problema.401Clave de API ausente o desconocida.402La billetera de créditos del espacio de trabajo no alcanza para cubrir la llamada;resetAtindica cuándo se reinician los créditos.403La clave no tiene el alcance, o el plan no incluye la función.429Se superó el ritmo de solicitudes (por segundo, por minuto o por día); respetaRetry-After.
Obtener la fuente de video del LIVE de un creador
/v1/live/creators/{uid}/playbackLa URL de video firmada y con vencimiento de la sala LIVE actual del creador. Tu reproductor la carga directamente desde la CDN de TikTok (source: tiktok-cdn); RoomScope nunca hace de proxy del video. Se prefiere hlsUrl; flvUrl es la fuente de las salas que solo ofrecen FLV (reprodúcela con un motor MSE como mpegts.js); al menos una de las dos está presente con status: live, y expiresAt indica cuándo deja de funcionar esa URL. renditions suele estar vacío. avatarUrl, followerCount y region son null cuando no se conocen. Otras respuestas: status: offline (no está en vivo), status: no_playback (en vivo, pero TikTok no expone una fuente reproducible), 202 status: resolving (consulta la misma URL después de Retry-After), 503 collection_saturated o live_playback_upstream_unavailable (reintenta), y 503 live_playback_not_configured mientras la función está desactivada en este despliegue (no reintentes). Requiere el alcance live:stream, no live:read.
Parámetros de ruta
| Name | Type | Description |
|---|---|---|
uidRequired | string | Nombre de usuario del creador (linh.live); se ignora una @ inicial. |
Solicitud
curl "https://api.next.toktokdata.live/v1/live/creators/linh.live/playback" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Respuesta
{ "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}Errores
401Clave de API ausente o desconocida.402La billetera de créditos del espacio de trabajo no alcanza para cubrir la llamada;resetAtindica cuándo se reinician los créditos.403La clave no tiene el alcance, o el plan no incluye la función.429Se superó el ritmo de solicitudes (por segundo, por minuto o por día); respetaRetry-After.503No disponible temporalmente; reintenta después deRetry-Aftercuandoretryablesea true.
Poner en cola una actualización del estado en vivo
/v1/live/creators/{uid}/refreshPide a los workers que revisen ahora mismo si el creador está en vivo. Se cobra con la tarifa de actualización.
Parámetros de ruta
| Name | Type | Description |
|---|---|---|
uidRequired | string | Nombre de usuario del creador sin @ (linh.live) o ID numérico de usuario de TikTok. |
Solicitud
curl -X POST "https://api.next.toktokdata.live/v1/live/creators/linh.live/refresh" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Respuesta
{ "queued": true, "jobId": "1761994604935-0"}Errores
400Parámetro o cuerpo no válido;codeindica el problema.401Clave de API ausente o desconocida.402La billetera de créditos del espacio de trabajo no alcanza para cubrir la llamada;resetAtindica cuándo se reinician los créditos.403La clave no tiene el alcance, o el plan no incluye la función.429Se superó el ritmo de solicitudes (por segundo, por minuto o por día); respetaRetry-After.
Listar sesiones LIVE registradas
/v1/live/sessionsSesiones que RoomScope registró para los creadores de la lista de seguimiento del workspace y las salas que siguen sus miembros, de la más reciente a la más antigua; las sesiones de otros workspaces nunca aparecen. Una sesión aún en curso tiene endedAt: null.
Parámetros de consulta
| Name | Type | Description |
|---|---|---|
creatorUniqueIdOptional | string | Solo las sesiones de este creador (nombre de usuario sin @). |
cursorOptional | string | Cursor opaco tomado de nextCursor de la página anterior. |
limitOptional | integer | Sesiones por página. Rango 1–100. Default: 50 |
Solicitud
curl "https://api.next.toktokdata.live/v1/live/sessions" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Respuesta
{ "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 }}Errores
400Parámetro o cuerpo no válido;codeindica el problema.401Clave de API ausente o desconocida.402La billetera de créditos del espacio de trabajo no alcanza para cubrir la llamada;resetAtindica cuándo se reinician los créditos.403La clave no tiene el alcance, o el plan no incluye la función.429Se superó el ritmo de solicitudes (por segundo, por minuto o por día); respetaRetry-After.
Obtener una sesión LIVE
/v1/live/sessions/{session_id}Una sesión con los totales de regalos y de donantes. La sesión de un creador o sala que el workspace no sigue responde 404.
Parámetros de ruta
| Name | Type | Description |
|---|---|---|
session_idRequired | string | ID de la sesión tomado de la lista. |
Solicitud
curl "https://api.next.toktokdata.live/v1/live/sessions/f18eaa3e-a762-543d-9ea5-178271dc43f9" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Respuesta
{ "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 }}Errores
400Parámetro o cuerpo no válido;codeindica el problema.401Clave de API ausente o desconocida.402La billetera de créditos del espacio de trabajo no alcanza para cubrir la llamada;resetAtindica cuándo se reinician los créditos.403La clave no tiene el alcance, o el plan no incluye la función.429Se superó el ritmo de solicitudes (por segundo, por minuto o por día); respetaRetry-After.
Obtener una sesión LIVE minuto a minuto
/v1/live/sessions/{session_id}/timelineLa serie por minuto de la sesión desde su inicio: espectadores máximos, eventos, chats, me gusta, regalos, diamantes, nuevos gifters y cofres por minuto, con offsetMinutes desde el inicio. Solo salas grabadas; una sesión grabada antes de que existiera la serie no tiene minutos (coverageStatus: not-covered). Misma visibilidad que la propia sesión.
Parámetros de ruta
| Name | Type | Description |
|---|---|---|
session_idRequired | string | ID de la sesión tomado de la lista. |
Solicitud
curl "https://api.next.toktokdata.live/v1/live/sessions/f18eaa3e-a762-543d-9ea5-178271dc43f9/timeline" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Respuesta
{ "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 }}Errores
400Parámetro o cuerpo no válido;codeindica el problema.401Clave de API ausente o desconocida.402La billetera de créditos del espacio de trabajo no alcanza para cubrir la llamada;resetAtindica cuándo se reinician los créditos.403La clave no tiene el alcance, o el plan no incluye la función.429Se superó el ritmo de solicitudes (por segundo, por minuto o por día); respetaRetry-After.
Comparar sesiones LIVE
/v1/live/sessions/compareDe dos a cuatro sesiones lado a lado, cada una con sus totales y sus minutos alineados en offsetMinutes desde su propio inicio. Cualquier sesión que el workspace no siga responde 404.
Parámetros de consulta
| Name | Type | Description |
|---|---|---|
idsRequired | string | Ids de sesión separados por comas, de 2 a 4. |
Solicitud
curl "https://api.next.toktokdata.live/v1/live/sessions/compare?ids=value" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Respuesta
{ "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 }}Errores
400Parámetro o cuerpo no válido;codeindica el problema.401Clave de API ausente o desconocida.402La billetera de créditos del espacio de trabajo no alcanza para cubrir la llamada;resetAtindica cuándo se reinician los créditos.403La clave no tiene el alcance, o el plan no incluye la función.429Se superó el ritmo de solicitudes (por segundo, por minuto o por día); respetaRetry-After.