RoomScope

Last updated

Live

Recorded LIVE sessions and per-creator performance.

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.

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.

Scopelive:readCreditsCached read

Path parameters

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

Query parameters

Query parameters of 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.roomscope.io/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  },  "provenance": {    "observedAt": "2026-11-01T07:51:44.935Z",    "freshness": "historical",    "source": "platform_observed_live_stream",    "coverageStatus": "observed",    "methodologyVersion": "live-history-v1"  }}

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.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded; honour Retry-After.

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 of POST /v1/live/creators/{uid}/refresh
NameTypeDescription
uidRequired
stringCreator handle without @ (linh.live) or numeric TikTok user id.

Request

curl -X POST "https://api.roomscope.io/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.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded; honour Retry-After.

List recorded LIVE sessions

GET/v1/live/sessions

Sessions RoomScope recorded for the workspace's creators, newest first. A session still running has endedAt: null.

Scopelive:readCreditsCached read

Query parameters

Query parameters of 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.roomscope.io/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",    "coverageStatus": "observed",    "methodologyVersion": "live-history-v1"  }}

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.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded; honour Retry-After.

Get a LIVE session

GET/v1/live/sessions/{session_id}

One session with gift and gifter rollups.

Scopelive:readCreditsCached read

Path parameters

Path parameters of GET /v1/live/sessions/{session_id}
NameTypeDescription
session_idRequired
stringSession id from the list.

Request

curl "https://api.roomscope.io/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",    "coverageStatus": "stale",    "methodologyVersion": "live-history-v1"  }}

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.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded; honour Retry-After.
Was this page helpful?