Última actualización 1 nov 2026

LIVE

Sesiones LIVE registradas, rendimiento por creador y la fuente de video del LIVE.

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.

Obtener el rendimiento en LIVE de un creador

GET/v1/live/creators/{uid}/performance

Una fila por sesión registrada: duración, pico de espectadores, regalos, diamantes y donadores distintos.

Alcancelive:readCréditosLectura en caché

Parámetros de ruta

Parámetros de ruta · GET /v1/live/creators/{uid}/performance
Name	Type	Description
`uid`Required	string	Nombre de usuario del creador sin `@` (`linh.live`) o ID numérico de usuario de TikTok.

Parámetros de consulta

Parámetros de consulta · GET /v1/live/creators/{uid}/performance
Name	Type	Description
`cursor`Optional	string	Cursor opaco tomado de `nextCursor` de la página anterior.
`limit`Optional	integer	Filas por página. Rango 1–100. Default: `50`

Solicitud

curl "https://api.toktokdata.live/v1/live/creators/linh.live/performance" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Respuesta

200 OK

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

400 Parámetro o cuerpo no válido; code indica el problema.
401 Clave de API ausente o desconocida.
402 La billetera de créditos del espacio de trabajo no alcanza para cubrir la llamada; resetAt indica cuándo se reinician los créditos.
403 La clave no tiene el alcance, o el plan no incluye la función.
429 Se superó el ritmo de solicitudes; respeta Retry-After.

Obtener la fuente de video del LIVE de un creador

GET/v1/live/creators/{uid}/playback

La 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.

Alcancelive:streamCréditosLectura en caché

Parámetros de ruta

Parámetros de ruta · GET /v1/live/creators/{uid}/playback
Name	Type	Description
`uid`Required	string	Nombre de usuario del creador (`linh.live`); se ignora una `@` inicial.

Solicitud

curl "https://api.toktokdata.live/v1/live/creators/linh.live/playback" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Respuesta

200 OK

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

401 Clave de API ausente o desconocida.
402 La billetera de créditos del espacio de trabajo no alcanza para cubrir la llamada; resetAt indica cuándo se reinician los créditos.
403 La clave no tiene el alcance, o el plan no incluye la función.
429 Se superó el ritmo de solicitudes; respeta Retry-After.
503 No disponible temporalmente; reintenta después de Retry-After cuando retryable sea true.

Poner en cola una actualización del estado en vivo

POST/v1/live/creators/{uid}/refresh

Pide a los workers que revisen ahora mismo si el creador está en vivo. Se cobra con la tarifa de actualización.

Alcancelive:readCréditosActualización en vivo

Parámetros de ruta

Parámetros de ruta · POST /v1/live/creators/{uid}/refresh
Name	Type	Description
`uid`Required	string	Nombre de usuario del creador sin `@` (`linh.live`) o ID numérico de usuario de TikTok.

Solicitud

curl -X POST "https://api.toktokdata.live/v1/live/creators/linh.live/refresh" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Respuesta

202 Aceptado

{  "queued": true,  "jobId": "1761994604935-0"}

Errores

400 Parámetro o cuerpo no válido; code indica el problema.
401 Clave de API ausente o desconocida.
402 La billetera de créditos del espacio de trabajo no alcanza para cubrir la llamada; resetAt indica cuándo se reinician los créditos.
403 La clave no tiene el alcance, o el plan no incluye la función.
429 Se superó el ritmo de solicitudes; respeta Retry-After.

Listar sesiones LIVE registradas

GET/v1/live/sessions

Sesiones que RoomScope registró para los creadores del espacio de trabajo, de la más reciente a la más antigua. Una sesión que sigue en curso tiene endedAt: null.

Alcancelive:readCréditosLectura en caché

Parámetros de consulta

Parámetros de consulta · GET /v1/live/sessions
Name	Type	Description
`creatorUniqueId`Optional	string	Solo las sesiones de este creador (nombre de usuario sin `@`).
`cursor`Optional	string	Cursor opaco tomado de `nextCursor` de la página anterior.
`limit`Optional	integer	Sesiones por página. Rango 1–100. Default: `50`

Solicitud

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

Respuesta

200 OK

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

400 Parámetro o cuerpo no válido; code indica el problema.
401 Clave de API ausente o desconocida.
402 La billetera de créditos del espacio de trabajo no alcanza para cubrir la llamada; resetAt indica cuándo se reinician los créditos.
403 La clave no tiene el alcance, o el plan no incluye la función.
429 Se superó el ritmo de solicitudes; respeta Retry-After.

Obtener una sesión LIVE

GET/v1/live/sessions/{session_id}

Una sesión con los totales de regalos y donadores.

Alcancelive:readCréditosLectura en caché

Parámetros de ruta

Parámetros de ruta · GET /v1/live/sessions/{session_id}
Name	Type	Description
`session_id`Required	string	ID de la sesión tomado de la lista.

Solicitud

curl "https://api.toktokdata.live/v1/live/sessions/f18eaa3e-a762-543d-9ea5-178271dc43f9" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Respuesta

200 OK

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

400 Parámetro o cuerpo no válido; code indica el problema.
401 Clave de API ausente o desconocida.
402 La billetera de créditos del espacio de trabajo no alcanza para cubrir la llamada; resetAt indica cuándo se reinician los créditos.
403 La clave no tiene el alcance, o el plan no incluye la función.
429 Se superó el ritmo de solicitudes; respeta Retry-After.

¿Te resultó útil esta página?