Last updated
Live
Recorded LIVE sessions, per-creator performance, the LIVE video source and recent LIVE chat.
Every operation authenticates with an API key (Authorization: Bearer <key>) and errors use the shared envelope described in Errors. Generated from the API’s OpenAPI document.
List gifters
/v1/giftersWho gifts in the LIVE rooms RoomScope recorded over the last 7 or 30 days, by diamonds: gift count, sessions, creators gifted, the creator of the last room and the previous window's diamonds. Each gifter has a segment: whale (at least 10,000 diamonds in 7 days or 30,000 in 30 days), rising (at least 1,000 diamonds and twice the previous window), regular (3 sessions or more), one_time (one session) or occasional. region keeps gifts to creators of that region. Coverage is always partial. Needs the Pro plan or above.
Query parameters
| Name | Type | Description |
|---|---|---|
windowOptional | "7d" | "30d" | 7d or 30d.Default: 7d |
segmentOptional | "whale" | "rising" | "regular" | "one_time" | "occasional" | Only one segment. |
regionOptional | string | Region of the creators gifted (e.g. VN). |
limitOptional | integer | Maximum rows. Range …–500. Default: 50 |
Request
curl "https://api.next.toktokdata.live/v1/gifters" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "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" } }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
List gifts
/v1/giftsThe TikTok gifts seen in the LIVE rooms RoomScope recorded, with the coins of one gift, the regions they were sent in and when they were first and last seen. isGlobal is true when a gift was seen in at least 3 regions. Images and gifts nobody sent yet are not included, so coverage is partial. Synced daily.
Query parameters
| Name | Type | Description |
|---|---|---|
qOptional | string | Part of the gift name. |
minCoinsOptional | integer | Minimum coins of one gift. |
maxCoinsOptional | integer | Maximum coins of one gift. |
regionOptional | string | Only gifts seen in this region (e.g. VN). |
sortOptional | "coins" | "name" | "recent" | coins (most first), name or recent.Default: coins |
limitOptional | integer | Maximum rows. Range …–500. Default: 100 |
Request
curl "https://api.next.toktokdata.live/v1/gifts" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "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 }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Get a creator's recent LIVE chat
/v1/live/creators/{uid}/commentsThe latest chat comments of the creator's LIVE room, oldest first, for a chat panel next to the player. Poll it every few seconds and pass the previous answer's cursor as after to get only newer comments (at most 100 per answer; when more arrived, the newest 100). Comments exist only for rooms RoomScope follows and that your workspace follows (watchlist or room subscription): status: tracked with roomId, otherwise status: not_tracked with no items (followed says whether your workspace follows the creator). RoomScope keeps the last 200 comments of a room for 10 minutes after the last one. Free (no credits), limited to 60 requests a minute per user (429 with Retry-After beyond that).
Path parameters
| Name | Type | Description |
|---|---|---|
uidRequired | string | Creator handle (linh.live); a leading @ is ignored. |
Query parameters
| Name | Type | Description |
|---|---|---|
afterOptional | string | cursor of the previous answer: only newer comments. |
Request
curl "https://api.next.toktokdata.live/v1/live/creators/linh.live/comments" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "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 }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.503Temporarily unavailable; retry afterRetry-Afterwhenretryableis true.
Get a creator's LIVE performance
/v1/live/creators/{uid}/performanceOne row per recorded session: duration, peak viewers, gifts, diamonds and distinct gifters. Only for a creator on the workspace's watchlist or a room its members track; otherwise items is empty and followed is false.
Path parameters
| Name | Type | Description |
|---|---|---|
uidRequired | string | Creator handle without @ (linh.live) or numeric TikTok user id. |
Query parameters
| Name | Type | Description |
|---|---|---|
cursorOptional | string | Opaque cursor from nextCursor of the previous page. |
limitOptional | integer | Rows per page. Range 1–100. Default: 50 |
Request
curl "https://api.next.toktokdata.live/v1/live/creators/linh.live/performance" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "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 }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Get a creator's LIVE video source
/v1/live/creators/{uid}/playbackThe signed, expiring video URL of the creator's current LIVE room. Your player loads it directly from TikTok's CDN (source: tiktok-cdn); RoomScope never proxies the video. hlsUrl is preferred; flvUrl is the source of FLV-only rooms (play it with an MSE engine such as mpegts.js); at least one is set on status: live, and expiresAt is when that URL stops working. renditions is often empty. avatarUrl, followerCount and region are null when unknown. Other answers: status: offline (not live), status: no_playback (live, but TikTok exposes no playable source), 202 status: resolving (poll the same URL after Retry-After), 503 collection_saturated or live_playback_upstream_unavailable (retry), and 503 live_playback_not_configured while the feature is off on this deployment (do not retry). Needs the live:stream scope, not live:read.
Path parameters
| Name | Type | Description |
|---|---|---|
uidRequired | string | Creator handle (linh.live); a leading @ is ignored. |
Request
curl "https://api.next.toktokdata.live/v1/live/creators/linh.live/playback" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "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}Errors
401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.503Temporarily unavailable; retry afterRetry-Afterwhenretryableis true.
Queue a live-status refresh
/v1/live/creators/{uid}/refreshAsks the workers to check now whether the creator is live. Billed at the refresh rate.
Path parameters
| Name | Type | Description |
|---|---|---|
uidRequired | string | Creator handle without @ (linh.live) or numeric TikTok user id. |
Request
curl -X POST "https://api.next.toktokdata.live/v1/live/creators/linh.live/refresh" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "queued": true, "jobId": "1761994604935-0"}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
List recorded LIVE sessions
/v1/live/sessionsSessions RoomScope recorded for the creators on the workspace's watchlist and the rooms its members track, newest first; other workspaces' sessions never appear. A session still running has endedAt: null.
Query parameters
| Name | Type | Description |
|---|---|---|
creatorUniqueIdOptional | string | Only this creator's sessions (handle without @). |
cursorOptional | string | Opaque cursor from nextCursor of the previous page. |
limitOptional | integer | Sessions per page. Range 1–100. Default: 50 |
Request
curl "https://api.next.toktokdata.live/v1/live/sessions" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "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 }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Get a LIVE session
/v1/live/sessions/{session_id}One session with gift and gifter rollups. A session of a creator or room the workspace does not follow answers 404.
Path parameters
| Name | Type | Description |
|---|---|---|
session_idRequired | string | Session id from the list. |
Request
curl "https://api.next.toktokdata.live/v1/live/sessions/f18eaa3e-a762-543d-9ea5-178271dc43f9" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "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 }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Get a LIVE session minute by minute
/v1/live/sessions/{session_id}/timelineThe session's per-minute series from its start: peak viewers, events, chats, likes, gifts, diamonds, new gifters and treasure boxes per minute, with offsetMinutes since the start. Recorded rooms only; a session recorded before the series existed has no minutes (coverageStatus: not-covered). Same visibility as the session itself.
Path parameters
| Name | Type | Description |
|---|---|---|
session_idRequired | string | Session id from the list. |
Request
curl "https://api.next.toktokdata.live/v1/live/sessions/f18eaa3e-a762-543d-9ea5-178271dc43f9/timeline" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "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 }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Compare LIVE sessions
/v1/live/sessions/compareTwo to four sessions side by side, each with its totals and its minutes aligned on offsetMinutes since its own start. Any session the workspace does not follow answers 404.
Query parameters
| Name | Type | Description |
|---|---|---|
idsRequired | string | Comma-separated session ids, 2 to 4. |
Request
curl "https://api.next.toktokdata.live/v1/live/sessions/compare?ids=value" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "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 }}Errors
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.