RoomScope

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

GET/v1/gifters

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

Scopegifter:readCreditsCached read

Query parameters

Query parameters · GET /v1/gifters
NameTypeDescription
windowOptional
"7d" | "30d"7d or 30d.
Default: 7d
segmentOptional
"whale" | "rising" | "regular" | "one_time" | "occasional"Only one segment.
regionOptional
stringRegion of the creators gifted (e.g. VN).
limitOptional
integerMaximum rows. Range …–500.
Default: 50

Request

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

Response

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

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 402 The workspace's credit wallet cannot cover the call; resetAt says when the credits reset.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded (per second, per minute or per day); honour Retry-After.

List gifts

GET/v1/gifts

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

Scopelive:readCreditsCached read

Query parameters

Query parameters · GET /v1/gifts
NameTypeDescription
qOptional
stringPart of the gift name.
minCoinsOptional
integerMinimum coins of one gift.
maxCoinsOptional
integerMaximum coins of one gift.
regionOptional
stringOnly gifts seen in this region (e.g. VN).
sortOptional
"coins" | "name" | "recent"coins (most first), name or recent.
Default: coins
limitOptional
integerMaximum rows. Range …–500.
Default: 100

Request

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

Response

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

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 402 The workspace's credit wallet cannot cover the call; resetAt says when the credits reset.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded (per second, per minute or per day); honour Retry-After.

Get a creator's recent LIVE chat

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

The 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).

Scopelive:readCreditsFree

Path parameters

Path parameters · GET /v1/live/creators/{uid}/comments
NameTypeDescription
uidRequired
stringCreator handle (linh.live); a leading @ is ignored.

Query parameters

Query parameters · GET /v1/live/creators/{uid}/comments
NameTypeDescription
afterOptional
stringcursor 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

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

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded (per second, per minute or per day); honour Retry-After.
  • 503 Temporarily unavailable; retry after Retry-After when retryable is true.

Get a creator's LIVE performance

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

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

Scopelive:readCreditsCached read

Path parameters

Path parameters · GET /v1/live/creators/{uid}/performance
NameTypeDescription
uidRequired
stringCreator handle without @ (linh.live) or numeric TikTok user id.

Query parameters

Query parameters · GET /v1/live/creators/{uid}/performance
NameTypeDescription
cursorOptional
stringOpaque cursor from nextCursor of the previous page.
limitOptional
integerRows 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

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

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 402 The workspace's credit wallet cannot cover the call; resetAt says when the credits reset.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded (per second, per minute or per day); honour Retry-After.

Get a creator's LIVE video source

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

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

Scopelive:streamCreditsCached read

Path parameters

Path parameters · GET /v1/live/creators/{uid}/playback
NameTypeDescription
uidRequired
stringCreator 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

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}

Errors

  • 401 Missing or unknown API key.
  • 402 The workspace's credit wallet cannot cover the call; resetAt says when the credits reset.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded (per second, per minute or per day); honour Retry-After.
  • 503 Temporarily unavailable; retry after Retry-After when retryable is true.

Queue a live-status refresh

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

Asks the workers to check now whether the creator is live. Billed at the refresh rate.

Scopelive:readCreditsLive refresh

Path parameters

Path parameters · POST /v1/live/creators/{uid}/refresh
NameTypeDescription
uidRequired
stringCreator 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

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

Errors

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 402 The workspace's credit wallet cannot cover the call; resetAt says when the credits reset.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded (per second, per minute or per day); honour Retry-After.

List recorded LIVE sessions

GET/v1/live/sessions

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

Scopelive:readCreditsCached read

Query parameters

Query parameters · GET /v1/live/sessions
NameTypeDescription
creatorUniqueIdOptional
stringOnly this creator's sessions (handle without @).
cursorOptional
stringOpaque cursor from nextCursor of the previous page.
limitOptional
integerSessions per page. Range 1–100.
Default: 50

Request

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

Response

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  }}

Errors

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 402 The workspace's credit wallet cannot cover the call; resetAt says when the credits reset.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded (per second, per minute or per day); honour Retry-After.

Get a LIVE session

GET/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.

Scopelive:readCreditsCached read

Path parameters

Path parameters · GET /v1/live/sessions/{session_id}
NameTypeDescription
session_idRequired
stringSession 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

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  }}

Errors

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 402 The workspace's credit wallet cannot cover the call; resetAt says when the credits reset.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded (per second, per minute or per day); honour Retry-After.

Get a LIVE session minute by minute

GET/v1/live/sessions/{session_id}/timeline

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

Scopelive:readCreditsCached read

Path parameters

Path parameters · GET /v1/live/sessions/{session_id}/timeline
NameTypeDescription
session_idRequired
stringSession 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

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

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 402 The workspace's credit wallet cannot cover the call; resetAt says when the credits reset.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded (per second, per minute or per day); honour Retry-After.

Compare LIVE sessions

GET/v1/live/sessions/compare

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

Scopelive:readCreditsCached read

Query parameters

Query parameters · GET /v1/live/sessions/compare
NameTypeDescription
idsRequired
stringComma-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

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

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 402 The workspace's credit wallet cannot cover the call; resetAt says when the credits reset.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded (per second, per minute or per day); honour Retry-After.
Was this page helpful?