RoomScope

最終更新

LIVE

記録した LIVE セッション、クリエイターごとのパフォーマンス、LIVE の映像ソース。

すべての操作は API キーで認証します (Authorization: Bearer <key>) 。エラーには共通のエンベロープを使用します。詳しくは次のページを参照してください： エラー. このページは API の OpenAPI ドキュメントから生成しています。

クリエイターの LIVE パフォーマンスを取得

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

記録したセッションごとに 1 行：配信時間、最大視聴者数、ギフト、ダイヤモンド、ギフターの人数（重複なし）。

スコープlive:readクレジットキャッシュの閲覧

パスパラメーター

パスパラメーター · GET /v1/live/creators/{uid}/performance
NameTypeDescription
uidRequired
string@ なしのクリエイターのハンドル（linh.live）、または数値の TikTok ユーザー ID。

クエリパラメーター

クエリパラメーター · GET /v1/live/creators/{uid}/performance
NameTypeDescription
cursorOptional
string前のページの nextCursor から得た不透明なカーソル。
limitOptional
integer1 ページあたりの行数。 範囲 1–100.
Default: 50

リクエスト

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

レスポンス

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

エラー

  • 400 パラメーターまたはボディが不正です。問題の内容は code で示されます。
  • 401 API キーがないか、不明なキーです。
  • 402 ワークスペースのクレジットウォレットでこの呼び出しをまかなえません。クレジットがリセットされる日時は resetAt で示されます。
  • 403 キーに必要なスコープがないか、プランにその機能が含まれていません。
  • 429 リクエストレートを超えました。Retry-After に従ってください。

クリエイターの LIVE 映像ソースを取得

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

クリエイターの現在の LIVE ルームの、署名付きで有効期限のある映像 URL。プレーヤーは TikTok の CDN から直接読み込みます（source: tiktok-cdn）。RoomScope が映像をプロキシすることはありません。hlsUrl を優先してください。flvUrl は FLV のみのルームのソースです（mpegts.js などの MSE エンジンで再生します）。status: live の場合は少なくとも一方が設定され、expiresAt はその URL が使えなくなる日時です。renditions は空であることが多くあります。avatarUrl、followerCount、region は不明な場合 null です。その他の応答：status: offline（配信していない）、status: no_playback（配信中だが TikTok が再生可能なソースを公開していない）、202 status: resolving（Retry-After の後に同じ URL をポーリング）、503 collection_saturated または live_playback_upstream_unavailable（リトライ）、そしてこのデプロイで機能が無効な間は 503 live_playback_not_configured（リトライしない）。live:read ではなく live:stream スコープが必要です。

スコープlive:streamクレジットキャッシュの閲覧

パスパラメーター

パスパラメーター · GET /v1/live/creators/{uid}/playback
NameTypeDescription
uidRequired
stringクリエイターのハンドル（linh.live）。先頭の @ は無視されます。

リクエスト

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

レスポンス

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}

エラー

  • 401 API キーがないか、不明なキーです。
  • 402 ワークスペースのクレジットウォレットでこの呼び出しをまかなえません。クレジットがリセットされる日時は resetAt で示されます。
  • 403 キーに必要なスコープがないか、プランにその機能が含まれていません。
  • 429 リクエストレートを超えました。Retry-After に従ってください。
  • 503 一時的に利用できません。retryable が true の場合は Retry-After の後にリトライしてください。

ライブ状態の更新を予約

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

クリエイターが配信中かどうかを今すぐ確認するようワーカーに依頼します。更新の料金で課金されます。

スコープlive:readクレジットライブ状態の更新

パスパラメーター

パスパラメーター · POST /v1/live/creators/{uid}/refresh
NameTypeDescription
uidRequired
string@ なしのクリエイターのハンドル（linh.live）、または数値の TikTok ユーザー ID。

リクエスト

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

レスポンス

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

エラー

  • 400 パラメーターまたはボディが不正です。問題の内容は code で示されます。
  • 401 API キーがないか、不明なキーです。
  • 402 ワークスペースのクレジットウォレットでこの呼び出しをまかなえません。クレジットがリセットされる日時は resetAt で示されます。
  • 403 キーに必要なスコープがないか、プランにその機能が含まれていません。
  • 429 リクエストレートを超えました。Retry-After に従ってください。

記録した LIVE セッションを一覧表示

GET/v1/live/sessions

RoomScope がワークスペースのクリエイターについて記録したセッションを新しい順に返します。進行中のセッションは endedAt: null です。

スコープlive:readクレジットキャッシュの閲覧

クエリパラメーター

クエリパラメーター · GET /v1/live/sessions
NameTypeDescription
creatorUniqueIdOptional
stringこのクリエイターのセッションのみ（@ なしのハンドル）。
cursorOptional
string前のページの nextCursor から得た不透明なカーソル。
limitOptional
integer1 ページあたりのセッション数。 範囲 1–100.
Default: 50

リクエスト

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

レスポンス

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

エラー

  • 400 パラメーターまたはボディが不正です。問題の内容は code で示されます。
  • 401 API キーがないか、不明なキーです。
  • 402 ワークスペースのクレジットウォレットでこの呼び出しをまかなえません。クレジットがリセットされる日時は resetAt で示されます。
  • 403 キーに必要なスコープがないか、プランにその機能が含まれていません。
  • 429 リクエストレートを超えました。Retry-After に従ってください。

LIVE セッションを取得

GET/v1/live/sessions/{session_id}

ギフトとギフターの集計を含むセッション 1 件。

スコープlive:readクレジットキャッシュの閲覧

パスパラメーター

パスパラメーター · GET /v1/live/sessions/{session_id}
NameTypeDescription
session_idRequired
string一覧から得たセッション ID。

リクエスト

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

レスポンス

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

エラー

  • 400 パラメーターまたはボディが不正です。問題の内容は code で示されます。
  • 401 API キーがないか、不明なキーです。
  • 402 ワークスペースのクレジットウォレットでこの呼び出しをまかなえません。クレジットがリセットされる日時は resetAt で示されます。
  • 403 キーに必要なスコープがないか、プランにその機能が含まれていません。
  • 429 リクエストレートを超えました。Retry-After に従ってください。
このページは役に立ちましたか？