RoomScope

최종 업데이트

LIVE

기록된 LIVE 세션, 크리에이터별 성과, LIVE 영상 소스.

모든 작업은 API key로 인증하며 (Authorization: Bearer <key>) 오류 응답은 다음 문서에서 설명하는 공통 오류 형식을 따릅니다: 오류. 이 페이지는 API의 OpenAPI 문서에서 생성되었습니다.

크리에이터의 LIVE 성과 조회

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

기록된 세션마다 한 행: 방송 시간, 최고 시청자 수, 선물, 다이아몬드, 고유 후원자 수.

스코프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
integer페이지당 행 수. 범위 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 key가 없거나 알 수 없는 key입니다.
  • 402 워크스페이스의 크레딧 지갑으로 이 호출을 처리할 수 없습니다. resetAt에 크레딧이 초기화되는 시점이 나와 있습니다.
  • 403 key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.
  • 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 key가 없거나 알 수 없는 key입니다.
  • 402 워크스페이스의 크레딧 지갑으로 이 호출을 처리할 수 없습니다. resetAt에 크레딧이 초기화되는 시점이 나와 있습니다.
  • 403 key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.
  • 429 요청 속도를 초과했습니다. Retry-After를 따르세요.
  • 503 일시적으로 이용할 수 없습니다. retryable이 true이면 Retry-After 후에 재시도하세요.

LIVE 상태 새로고침 요청

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

크리에이터가 방송 중인지 지금 확인하도록 워커에게 요청합니다. 새로고침 요금으로 과금됩니다.

스코프live:read크레딧LIVE 새로고침

경로 파라미터

경로 파라미터 · 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 key가 없거나 알 수 없는 key입니다.
  • 402 워크스페이스의 크레딧 지갑으로 이 호출을 처리할 수 없습니다. resetAt에 크레딧이 초기화되는 시점이 나와 있습니다.
  • 403 key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.
  • 429 요청 속도를 초과했습니다. Retry-After를 따르세요.

기록된 LIVE 세션 목록 조회

GET/v1/live/sessions

RoomScope가 워크스페이스의 크리에이터에 대해 기록한 세션, 최신순. 아직 진행 중인 세션은 endedAt: null입니다.

스코프live:read크레딧캐시 조회

쿼리 파라미터

쿼리 파라미터 · GET /v1/live/sessions
NameTypeDescription
creatorUniqueIdOptional
string이 크리에이터의 세션만(@를 제외한 핸들).
cursorOptional
string이전 페이지의 nextCursor에서 받은 불투명 커서.
limitOptional
integer페이지당 세션 수. 범위 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 key가 없거나 알 수 없는 key입니다.
  • 402 워크스페이스의 크레딧 지갑으로 이 호출을 처리할 수 없습니다. resetAt에 크레딧이 초기화되는 시점이 나와 있습니다.
  • 403 key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.
  • 429 요청 속도를 초과했습니다. Retry-After를 따르세요.

LIVE 세션 조회

GET/v1/live/sessions/{session_id}

선물 및 후원자 집계가 포함된 세션 하나.

스코프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 key가 없거나 알 수 없는 key입니다.
  • 402 워크스페이스의 크레딧 지갑으로 이 호출을 처리할 수 없습니다. resetAt에 크레딧이 초기화되는 시점이 나와 있습니다.
  • 403 key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.
  • 429 요청 속도를 초과했습니다. Retry-After를 따르세요.
이 페이지가 도움이 되었나요?