RoomScope

Última actualización

Creadores

Perfiles de creadores almacenados, cambios, red de seguidos y analítica.

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 agencias de TikTok LIVE

GET/v1/agencies

Agencias de TikTok LIVE (de sus perfiles públicos de agencia), con búsqueda por nombre o nombre de usuario oficial, por región y por perfil público, ordenadas por tamaño (hostCountMin), franja de ingresos (monthlyDiamondMin), más recientes o nombre. Las franjas son los rangos del propio TikTok. Los datos de contacto muestran solo lo que la agencia publicó.

Alcancecreator:readCréditosLectura en caché

Parámetros de consulta

Parámetros de consulta · GET /v1/agencies
NameTypeDescription
qOptional
stringParte del nombre de la agencia, o su nombre de usuario oficial.
regionOptional
stringGrupo de regiones (p. ej., VN, US+, MENA).
publicOnlyOptional
booleanSolo agencias con perfil público.
sortOptional
"size" | "revenue" | "recent" | "name"size, revenue, recent o name.
Default: size
limitOptional
integerMáximo de filas. Rango …–200.
Default: 50
offsetOptional
integerFilas que se omiten.
Default: 0

Solicitud

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

Respuesta

200 OK
{  "data": {    "agencies": [      {        "agencyId": "108474",        "name": "Look Corporation",        "regions": [          "KR"        ],        "onboardedOn": "2025-03-01",        "official": {          "uid": "7012345678901234567",          "handle": "look.corp",          "nickname": "Look Corporation",          "avatarUrl": null,          "followers": 12500        },        "intro": "A TikTok LIVE agency based in Korea.",        "services": [          "1_on_1_support",          "live_skills_training"        ],        "contact": {          "website": "https://example.com"        },        "hostCountBand": "101-200",        "agentCountBand": "11-50",        "monthlyDiamondBand": "1M-5M",        "hostCountMin": 101,        "monthlyDiamondMin": 1000000,        "hasPublicProfile": true,        "lastSeenAt": "2026-10-24T05:34:33.738Z"      }    ],    "total": 1,    "offset": 0  },  "provenance": {    "observedAt": "2026-10-24T05:34:33.738Z",    "freshness": "stale",    "source": "public_creator_profile",    "sourceKind": "derived",    "coverageStatus": "partial",    "methodologyVersion": "agency-directory-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 (por segundo, por minuto o por día); respeta Retry-After.

Obtener una agencia de TikTok LIVE

GET/v1/agencies/{agency_id}

Una agencia del directorio, tal como la lista GET /v1/agencies.

Alcancecreator:readCréditosLectura en caché

Parámetros de ruta

Parámetros de ruta · GET /v1/agencies/{agency_id}
NameTypeDescription
agency_idRequired
stringID de agencia de TikTok.

Solicitud

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

Respuesta

200 OK
{  "data": {    "agencyId": "108474",    "name": "Look Corporation",    "regions": [      "KR"    ],    "onboardedOn": "2025-03-01",    "official": {      "uid": "7012345678901234567",      "handle": "look.corp",      "nickname": "Look Corporation",      "avatarUrl": null,      "followers": 12500    },    "intro": "A TikTok LIVE agency based in Korea.",    "services": [      "1_on_1_support",      "live_skills_training"    ],    "contact": {      "website": "https://example.com"    },    "hostCountBand": "101-200",    "agentCountBand": "11-50",    "monthlyDiamondBand": "1M-5M",    "hostCountMin": 101,    "monthlyDiamondMin": 1000000,    "hasPublicProfile": true,    "lastSeenAt": "2026-10-24T05:34:33.738Z"  },  "provenance": {    "observedAt": "2026-10-24T05:34:33.738Z",    "freshness": "stale",    "source": "public_creator_profile",    "sourceKind": "derived",    "coverageStatus": "partial",    "methodologyVersion": "agency-directory-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 (por segundo, por minuto o por día); respeta Retry-After.

Buscar creadores

GET/v1/creators

Subcadena del nombre de usuario o del nombre visible, sin distinguir mayúsculas de minúsculas, primero los más seguidos. Un q vacío recorre el conjunto almacenado.

Alcancecreator:readCréditosLectura en caché

Parámetros de consulta

Parámetros de consulta · GET /v1/creators
NameTypeDescription
qOptional
stringNombre de usuario (con o sin @) o parte del nombre visible.
limitOptional
integerMáximo de resultados. Rango 1–100.
Default: 20

Solicitud

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

Respuesta

200 OK
{  "data": {    "query": "linh.live",    "results": [      {        "tiktokUserId": "990000000000000001",        "uniqueId": "linh.live",        "displayName": "Linh Live",        "region": "VN",        "avatarUrl": null,        "followerCount": 123456,        "verified": true      }    ]  },  "provenance": {    "observedAt": "2026-11-01T10:36:44.935Z",    "freshness": "near_realtime",    "source": "public_creator_profile",    "sourceKind": "derived",    "coverageStatus": "observed",    "methodologyVersion": "creators-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 (por segundo, por minuto o por día); respeta Retry-After.

Obtener el perfil de un creador

GET/v1/creators/{uid}

El perfil público guardado y el historial reciente de sus contadores. Un creador aún no guardado (o guardado hace tiempo) se busca en TikTok: si tarda más de unos segundos, la respuesta es 202 con status: resolving, un jobId y retryAfterSeconds (también Retry-After); vuelve a preguntar entonces y el perfil estará. status: saturated (202) significa que hay demasiadas búsquedas en curso; un usuario que TikTok no conoce es un 404 y no se vuelve a buscar durante diez minutos; 503 resolve_unavailable significa que ahora no se pudo leer TikTok.

Alcancecreator:readCréditosLectura en caché

Parámetros de ruta

Parámetros de ruta · GET /v1/creators/{uid}
NameTypeDescription
uidRequired
stringNombre de usuario del creador sin @ (linh.live) o ID numérico de usuario de TikTok.

Solicitud

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

Respuesta

200 OK
{  "data": {    "creator": {      "tiktokUserId": "990000000000000001",      "uniqueId": "linh.live",      "secUid": null,      "displayName": "Linh Live",      "region": "VN",      "language": null,      "signature": "Daily LIVE from Hanoi",      "avatarUrl": null,      "followerCount": 123456,      "followingCount": 321,      "awemeCount": 3,      "totalFavorited": 9876543,      "favoritingCount": null,      "verified": true,      "customVerify": null,      "enterpriseVerifyReason": null,      "instagramId": null,      "youtubeChannelId": null,      "twitterId": null,      "firstSeenAt": "2026-10-02T10:51:44.935Z",      "lastRefreshedAt": "2026-11-01T10:36:44.935Z",      "history": []    }  },  "provenance": {    "observedAt": "2026-11-01T10:36:44.935Z",    "freshness": "near_realtime",    "source": "public_creator_profile",    "sourceKind": "derived",    "coverageStatus": "observed",    "methodologyVersion": "creators-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 (por segundo, por minuto o por día); respeta Retry-After.

Analizar los videos de un creador

GET/v1/creators/{uid}/analysis

Informe de interacción calculado solo con los videos guardados: totales, medianas y ritmo de publicación. read son hasta cinco frases sencillas, la más reveladora primero, cada una un code (engagement, reach, growth, cadence, posting-gap, breakout, audience-language) con sus params, para que el cliente las redacte en su idioma; limits indica lo que el informe no cubre y por qué falta una frase.

Alcancecreator:readCréditosLectura en caché

Parámetros de ruta

Parámetros de ruta · GET /v1/creators/{uid}/analysis
NameTypeDescription
uidRequired
stringNombre de usuario del creador sin @ (linh.live) o ID numérico de usuario de TikTok.

Solicitud

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

Respuesta

200 OK
{  "data": {    "creator": {      "tiktokUserId": "990000000000000001",      "uniqueId": "linh.live",      "displayName": "Linh Live",      "avatarUrl": null,      "region": "VN",      "verified": true,      "followerCount": 123456,      "followingCount": 321,      "awemeCount": 3,      "totalFavorited": 9876543,      "firstSeenAt": "2026-10-02T10:51:44.935Z",      "lastRefreshedAt": "2026-11-01T10:36:44.935Z"    },    "sample": {      "videosAnalyzed": 3,      "oldestVideoAt": "2026-10-29T10:51:44.935Z",      "newestVideoAt": "2026-10-31T10:51:44.935Z",      "spanDays": 2,      "shareOfCatalog": 1    },    "engagement": {      "totalPlays": 60000,      "totalLikes": 6000,      "totalComments": 600,      "totalShares": 0,      "avgPlays": 20000,      "medianPlays": 20000,      "avgLikes": 2000,      "avgComments": 200,      "avgShares": 0,      "engagementRate": 0.11,      "likeRate": 0.1,      "commentRate": 0.01,      "shareRate": 0,      "viewsPerFollower": 0.162    },    "read": [      {        "code": "engagement",        "params": {          "rate": 0.11,          "band": "typical"        }      },      {        "code": "reach",        "params": {          "ratio": 0.162,          "band": "most-followers"        }      },      {        "code": "growth",        "params": {          "delta": 1840,          "rate": 0.0371,          "days": 29.8,          "direction": "up"        }      },      {        "code": "cadence",        "params": {          "postsPerWeek": 7,          "busiestWeekday": 4        }      }    ],    "cadence": {      "postsPerWeek": 7,      "avgDaysBetweenPosts": 1,      "longestGapDays": 1,      "busiestWeekday": 4,      "postsByWeekday": [        0,        0      ]    },    "topByPlays": [      {        "videoId": "7990000000000000003",        "description": "Video 3",        "createTime": "2026-10-29T10:51:44.935Z",        "playCount": 30000,        "diggCount": 3000,        "commentCount": 300,        "shareCount": null,        "engagementRate": 0.11      },      {        "videoId": "7990000000000000002",        "description": "Video 2",        "createTime": "2026-10-30T10:51:44.935Z",        "playCount": 20000,        "diggCount": 2000,        "commentCount": 200,        "shareCount": null,        "engagementRate": 0.11      }    ],    "topByEngagement": [      {        "videoId": "7990000000000000001",        "description": "Video 1",        "createTime": "2026-10-31T10:51:44.935Z",        "playCount": 10000,        "diggCount": 1000,        "commentCount": 100,        "shareCount": null,        "engagementRate": 0.11      },      {        "videoId": "7990000000000000002",        "description": "Video 2",        "createTime": "2026-10-30T10:51:44.935Z",        "playCount": 20000,        "diggCount": 2000,        "commentCount": 200,        "shareCount": null,        "engagementRate": 0.11      }    ],    "audience": null,    "growth": null,    "limits": [      {        "code": "thin-video-sample",        "message": "Only 3 video(s) analysed — too few to describe the account's typical performance."      },      {        "code": "single-observation",        "message": "This account has been observed only once, so no follower growth can be shown yet."      }    ]  },  "provenance": {    "observedAt": "2026-11-01T10:36:44.935Z",    "freshness": "near_realtime",    "source": "derived_creator_analysis",    "sourceKind": "derived",    "coverageStatus": "partial",    "methodologyVersion": "analysis-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 (por segundo, por minuto o por día); respeta Retry-After.

Listar cambios de perfil

GET/v1/creators/{uid}/changes

Cambios de nombre de usuario, nombre, biografía y verificación observados a lo largo del tiempo, del más reciente al más antiguo.

Alcancecreator:readCréditosLectura en caché

Parámetros de ruta

Parámetros de ruta · GET /v1/creators/{uid}/changes
NameTypeDescription
uidRequired
stringNombre 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/creators/{uid}/changes
NameTypeDescription
limitOptional
integerMáximo de cambios. Rango 1–200.
Default: 50

Solicitud

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

Respuesta

200 OK
{  "data": {    "tiktokUserId": "990000000000000001",    "uniqueId": "linh.live",    "changes": []  },  "provenance": {    "observedAt": "2026-10-02T10:51:44.935Z",    "freshness": "stale",    "source": "public_creator_profile",    "sourceKind": "derived",    "coverageStatus": "partial",    "methodologyVersion": "creators-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 (por segundo, por minuto o por día); respeta Retry-After.

Listar los seguidores de un creador

GET/v1/creators/{uid}/followers

Seguidores almacenados, con la misma estructura que los seguidos.

Alcancecreator:readCréditosLectura en caché

Parámetros de ruta

Parámetros de ruta · GET /v1/creators/{uid}/followers
NameTypeDescription
uidRequired
stringNombre 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/creators/{uid}/followers
NameTypeDescription
cursorOptional
stringCursor opaco tomado de nextCursor de la página anterior.
limitOptional
integerEntradas por página.

Solicitud

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

Respuesta

200 OK
{  "data": {    "tiktokUserId": "990000000000000001",    "uniqueId": "linh.live",    "direction": "following",    "entries": [],    "nextCursor": null,    "hasMore": false,    "totalReported": null,    "storedCount": 0,    "isPrivate": false  },  "provenance": {    "observedAt": "2026-11-01T11:18:49.084Z",    "freshness": "stale",    "source": "public_follow_graph",    "sourceKind": "derived",    "coverageStatus": "not-covered",    "methodologyVersion": "follow-list-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 (por segundo, por minuto o por día); respeta Retry-After.

Listar las cuentas que sigue un creador

GET/v1/creators/{uid}/following

Red de seguidos almacenada. Las cuentas privadas devuelven isPrivate: true y ninguna entrada.

Alcancecreator:readCréditosLectura en caché

Parámetros de ruta

Parámetros de ruta · GET /v1/creators/{uid}/following
NameTypeDescription
uidRequired
stringNombre 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/creators/{uid}/following
NameTypeDescription
cursorOptional
stringCursor opaco tomado de nextCursor de la página anterior.
limitOptional
integerEntradas por página.

Solicitud

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

Respuesta

200 OK
{  "data": {    "tiktokUserId": "990000000000000001",    "uniqueId": "linh.live",    "direction": "following",    "entries": [],    "nextCursor": null,    "hasMore": false,    "totalReported": null,    "storedCount": 0,    "isPrivate": false  },  "provenance": {    "observedAt": "2026-11-01T11:18:49.084Z",    "freshness": "stale",    "source": "public_follow_graph",    "sourceKind": "derived",    "coverageStatus": "not-covered",    "methodologyVersion": "follow-list-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 (por segundo, por minuto o por día); respeta Retry-After.

Obtener los top donadores de un creador

GET/v1/creators/{uid}/gifters

Donadores de las salas LIVE del creador en los últimos 7 o 30 días, por diamantes: cantidad de regalos, sesiones, último regalo y el creador de la última sala en la que enviaron regalos. Se lee de las sesiones que registró RoomScope, por lo que la cobertura siempre es partial. Requiere el plan Pro o superior.

Alcancegifter:readCréditosLectura en caché

Parámetros de ruta

Parámetros de ruta · GET /v1/creators/{uid}/gifters
NameTypeDescription
uidRequired
stringNombre 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/creators/{uid}/gifters
NameTypeDescription
windowOptional
"7d" | "30d"7d o 30d.
Default: 7d
limitOptional
integerMáximo de filas. Rango …–100.
Default: 20

Solicitud

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

Respuesta

200 OK
{  "data": {    "creatorUid": "7012345678901234567",    "uniqueId": "linh.live",    "window": "7d",    "gifters": [      {        "gifterUserId": "6987001122334455667",        "gifterUniqueId": "minh.fan",        "gifterNickname": "Minh",        "avatarUrl": null,        "diamondTotal": 18450,        "giftCount": 312,        "sessions": 4,        "lastGiftAt": "2026-11-02T15:41:07.512Z",        "lastRoomCreator": "linh.live"      }    ]  },  "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

  • 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 (por segundo, por minuto o por día); respeta Retry-After.

Obtener los insights de un creador

GET/v1/creators/{uid}/insights

Historial de nombres de usuario, diamantes diarios de los últimos 30 días (del más reciente al más antiguo), instantáneas diarias de liga y la sala LIVE del creador. liveExact es true cuando la puntuación del día se leyó en el reinicio del ranking; si no, liveScore es la puntuación más alta leída ese día. observedCoins cuenta los diamantes que RoomScope registró en las sesiones LIVE del creador. Un nombre de usuario que cambió se sigue resolviendo a través del historial de alias.

Alcancecreator:readCréditosLectura en caché

Parámetros de ruta

Parámetros de ruta · GET /v1/creators/{uid}/insights
NameTypeDescription
uidRequired
stringNombre de usuario del creador sin @ (linh.live) o ID numérico de usuario de TikTok.

Solicitud

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

Respuesta

200 OK
{  "data": {    "creator": {      "uid": "6990000000000000001",      "uniqueId": "linh.live"    },    "aliases": [      {        "uniqueId": "linh.live",        "firstSeenAt": "2026-10-12T09:15:02.118Z",        "lastSeenAt": "2026-11-01T14:02:41.530Z"      },      {        "uniqueId": "linh.official",        "firstSeenAt": "2026-09-30T11:40:19.004Z",        "lastSeenAt": "2026-10-12T08:55:47.912Z"      }    ],    "daily": [      {        "boardDay": "2026-10-31",        "countryCode": "VN",        "tiktokScore": 184250,        "observedCoins": 171932,        "liveScore": 184250,        "liveExact": true,        "leagueClass": "B2"      },      {        "boardDay": "2026-10-30",        "countryCode": "VN",        "tiktokScore": 97410,        "observedCoins": null,        "liveScore": 97410,        "liveExact": false,        "leagueClass": "B2"      }    ],    "league": [      {        "day": "2026-10-31",        "leagueClass": "B2",        "leagueRank": 14,        "leagueCountry": "VN",        "followers": 412880      }    ],    "roomOwner": {      "roomId": "7432000000000000001",      "ownerUid": "6990000000000000001",      "ownerUniqueId": "linh.live",      "claimantUid": null,      "reason": "claim_confirmed",      "checkedAt": "2026-11-01T14:00:03.221Z"    }  },  "provenance": {    "observedAt": "2026-11-01T14:02:41.530Z",    "freshness": "near_realtime",    "source": "creator_analytics",    "sourceKind": "derived",    "coverageStatus": "observed",    "methodologyVersion": "creator-analytics-v1",    "window": {      "from": "2026-10-02T14:02:41.530Z",      "to": "2026-11-01T14:02:41.530Z",      "label": "30d"    }  }}

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 (por segundo, por minuto o por día); respeta Retry-After.

Obtener el mejor horario para salir en LIVE

GET/v1/insights/best-time

Diamantes y horas-donador de las sesiones LIVE registradas de una región en los últimos windowDays días, por día de la semana (0 = lunes) y hora UTC. Se recalcula a diario; cells está vacío mientras no se haya registrado nada para la región.

Alcancecreator:readCréditosLectura en caché

Parámetros de consulta

Parámetros de consulta · GET /v1/insights/best-time
NameTypeDescription
regionOptional
stringCódigo de región ISO 3166-1 alfa-2.
Default: VN

Solicitud

curl "https://api.next.toktokdata.live/v1/insights/best-time" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Respuesta

200 OK
{  "data": {    "region": "VN",    "windowDays": 28,    "computedAt": "2026-11-01T01:00:04.870Z",    "cells": [      {        "weekday": 0,        "hour": 12,        "diamonds": 418230,        "gifterHours": 1874      },      {        "weekday": 0,        "hour": 13,        "diamonds": 652910,        "gifterHours": 2410      },      {        "weekday": 0,        "hour": 14,        "diamonds": 701455,        "gifterHours": 2689      }    ]  },  "provenance": {    "observedAt": "2026-11-01T01:00:04.870Z",    "freshness": "near_realtime",    "source": "creator_analytics",    "sourceKind": "derived",    "coverageStatus": "observed",    "methodologyVersion": "creator-analytics-v1",    "window": {      "from": "2026-10-04T01:00:04.870Z",      "to": "2026-11-01T01:00:04.870Z",      "label": "28d"    }  }}

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 (por segundo, por minuto o por día); respeta Retry-After.

Obtener la presencia en LIVE por hora

GET/v1/insights/presence

Por hora, cuántos de los creadores rankeados y monitoreados de la región estaban en vivo, de lo más antiguo a lo más reciente.

Alcancecreator:readCréditosLectura en caché

Parámetros de consulta

Parámetros de consulta · GET /v1/insights/presence
NameTypeDescription
regionOptional
stringCódigo de región ISO 3166-1 alfa-2.
Default: VN
hoursOptional
integerCuántas horas hacia atrás. Rango 1–168.
Default: 48

Solicitud

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

Respuesta

200 OK
{  "data": {    "region": "VN",    "hours": 48,    "points": [      {        "hourStart": "2026-11-01T12:00:00.000Z",        "liveCreators": 214,        "trackedCreators": 1630      },      {        "hourStart": "2026-11-01T13:00:00.000Z",        "liveCreators": 251,        "trackedCreators": 1642      },      {        "hourStart": "2026-11-01T14:00:00.000Z",        "liveCreators": 268,        "trackedCreators": 1655      }    ]  },  "provenance": {    "observedAt": "2026-11-01T14:05:01.402Z",    "freshness": "near_realtime",    "source": "creator_analytics",    "sourceKind": "derived",    "coverageStatus": "observed",    "methodologyVersion": "creator-analytics-v1",    "window": {      "from": "2026-10-30T14:05:01.402Z",      "to": "2026-11-01T14:05:01.402Z",      "label": "48h"    }  }}

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 (por segundo, por minuto o por día); respeta Retry-After.
¿Te resultó útil esta página?