RoomScope

최종 업데이트

LIVE

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

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

후원자 목록 조회

GET/v1/gifters

최근 7일 또는 30일 동안 RoomScope가 기록한 LIVE 방에서 선물한 후원자를 다이아몬드 기준으로 정렬합니다: 선물 수, 세션 수, 선물받은 크리에이터 수, 마지막 방의 크리에이터, 이전 기간의 다이아몬드. 후원자마다 세그먼트가 있습니다: whale(7일 동안 10,000 다이아몬드 이상 또는 30일 동안 30,000 이상), rising(1,000 다이아몬드 이상이면서 이전 기간의 두 배 이상), regular(3세션 이상), one_time(1세션) 또는 occasional. region을 지정하면 해당 지역 크리에이터에게 보낸 선물만 남깁니다. 커버리지는 항상 partial입니다. Pro 요금제 이상이 필요합니다.

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

쿼리 파라미터

쿼리 파라미터 · GET /v1/gifters
NameTypeDescription
windowOptional
"7d" | "30d"7d 또는 30d.
Default: 7d
segmentOptional
"whale" | "rising" | "regular" | "one_time" | "occasional"한 가지 세그먼트만.
regionOptional
string선물받은 크리에이터의 지역(예: VN).
limitOptional
integer최대 행 수. 범위 …–500.
Default: 50

요청

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

응답

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

오류

  • 400 파라미터 또는 본문이 잘못되었습니다. code에 문제가 표시됩니다.
  • 401 API key가 없거나 알 수 없는 key입니다.
  • 402 워크스페이스의 크레딧 지갑으로 이 호출을 처리할 수 없습니다. resetAt에 크레딧이 초기화되는 시점이 나와 있습니다.
  • 403 key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.
  • 429 요청 속도를 초과했습니다(초당, 분당 또는 일일). Retry-After를 따르세요.

선물 목록 조회

GET/v1/gifts

RoomScope가 기록한 LIVE 방에서 확인된 TikTok 선물을 선물 1개의 코인, 보내진 지역, 처음과 마지막으로 확인된 시점과 함께 보여 줍니다. isGlobal은 선물이 3개 이상의 지역에서 확인되었을 때 true입니다. 이미지와 아직 아무도 보내지 않은 선물은 포함되지 않으므로 커버리지는 partial입니다. 매일 동기화됩니다.

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

쿼리 파라미터

쿼리 파라미터 · GET /v1/gifts
NameTypeDescription
qOptional
string선물 이름의 일부.
minCoinsOptional
integer선물 1개의 최소 코인.
maxCoinsOptional
integer선물 1개의 최대 코인.
regionOptional
string이 지역에서 확인된 선물만(예: VN).
sortOptional
"coins" | "name" | "recent"coins(많은 순), name 또는 recent.
Default: coins
limitOptional
integer최대 행 수. 범위 …–500.
Default: 100

요청

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

응답

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

오류

  • 400 파라미터 또는 본문이 잘못되었습니다. code에 문제가 표시됩니다.
  • 401 API key가 없거나 알 수 없는 key입니다.
  • 402 워크스페이스의 크레딧 지갑으로 이 호출을 처리할 수 없습니다. resetAt에 크레딧이 초기화되는 시점이 나와 있습니다.
  • 403 key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.
  • 429 요청 속도를 초과했습니다(초당, 분당 또는 일일). Retry-After를 따르세요.

크리에이터의 최근 LIVE 채팅 가져오기

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

크리에이터 LIVE 방의 최신 채팅 댓글(오래된 순)로, 플레이어 옆 채팅 패널용입니다. 몇 초마다 호출하고 이전 응답의 cursor를 after로 넘기면 더 새로운 댓글만 받습니다(응답당 최대 100개, 더 많이 왔으면 최신 100개). 댓글은 RoomScope가 팔로우하고 워크스페이스가 팔로우하는(watchlist 또는 방 구독) 방에만 있습니다: roomId와 함께 status: tracked, 그렇지 않으면 항목 없이 status: not_tracked(followed는 워크스페이스가 크리에이터를 팔로우하는지 알려줍니다). RoomScope는 방의 마지막 댓글 200개를 마지막 댓글 이후 10분간 보관합니다. 무료(크레딧 없음), 사용자당 분당 60회 요청으로 제한(초과 시 Retry-After와 함께 429).

스코프live:read크레딧무료

경로 파라미터

경로 파라미터 · GET /v1/live/creators/{uid}/comments
NameTypeDescription
uidRequired
string크리에이터 핸들(linh.live). 앞에 붙은 @는 무시됩니다.

쿼리 파라미터

쿼리 파라미터 · GET /v1/live/creators/{uid}/comments
NameTypeDescription
afterOptional
string이전 응답의 cursor: 더 새로운 댓글만.

요청

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

응답

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

오류

  • 400 파라미터 또는 본문이 잘못되었습니다. code에 문제가 표시됩니다.
  • 401 API key가 없거나 알 수 없는 key입니다.
  • 403 key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.
  • 429 요청 속도를 초과했습니다(초당, 분당 또는 일일). Retry-After를 따르세요.
  • 503 일시적으로 이용할 수 없습니다. retryable이 true이면 Retry-After 후에 재시도하세요.

크리에이터의 LIVE 성과 조회

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

기록된 세션당 한 행: 방송 시간, 최고 시청자 수, 선물, 다이아몬드, 고유 선물자 수. 워크스페이스 관심 목록에 있는 크리에이터나 멤버가 추적하는 룸에만 해당하며, 그렇지 않으면 items가 비어 있고 followed는 false입니다.

스코프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.next.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,    "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  }}

오류

  • 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.next.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.next.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.next.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}

선물 및 선물자 집계가 포함된 세션 하나. 워크스페이스가 추적하지 않는 크리에이터나 룸의 세션은 404를 반환합니다.

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

경로 파라미터

경로 파라미터 · GET /v1/live/sessions/{session_id}
NameTypeDescription
session_idRequired
string목록에서 받은 세션 ID.

요청

curl "https://api.next.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를 따르세요.

LIVE 세션을 분 단위로 가져오기

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

세션 시작부터의 분 단위 시계열: 분마다 최대 시청자, 이벤트, 채팅, 좋아요, 선물, 다이아몬드, 신규 기프터, 보물상자와 시작 이후 offsetMinutes. 기록한 방만 해당하며, 시계열이 생기기 전에 기록된 세션은 분 데이터가 없습니다(coverageStatus: not-covered). 공개 범위는 세션과 같습니다.

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

경로 파라미터

경로 파라미터 · GET /v1/live/sessions/{session_id}/timeline
NameTypeDescription
session_idRequired
string목록에서 받은 세션 ID.

요청

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

응답

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

오류

  • 400 파라미터 또는 본문이 잘못되었습니다. code에 문제가 표시됩니다.
  • 401 API key가 없거나 알 수 없는 key입니다.
  • 402 워크스페이스의 크레딧 지갑으로 이 호출을 처리할 수 없습니다. resetAt에 크레딧이 초기화되는 시점이 나와 있습니다.
  • 403 key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.
  • 429 요청 속도를 초과했습니다(초당, 분당 또는 일일). Retry-After를 따르세요.

LIVE 세션 비교

GET/v1/live/sessions/compare

두 개에서 네 개의 세션을 나란히 보여 주며, 각각 합계와 자기 시작 이후 offsetMinutes로 맞춘 분 데이터를 포함합니다. 워크스페이스가 팔로우하지 않는 세션은 404를 반환합니다.

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

쿼리 파라미터

쿼리 파라미터 · GET /v1/live/sessions/compare
NameTypeDescription
idsRequired
string쉼표로 구분한 세션 ID, 2~4개.

요청

curl "https://api.next.toktokdata.live/v1/live/sessions/compare?ids=value" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

응답

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

오류

  • 400 파라미터 또는 본문이 잘못되었습니다. code에 문제가 표시됩니다.
  • 401 API key가 없거나 알 수 없는 key입니다.
  • 402 워크스페이스의 크레딧 지갑으로 이 호출을 처리할 수 없습니다. resetAt에 크레딧이 초기화되는 시점이 나와 있습니다.
  • 403 key에 필요한 스코프가 없거나, 요금제에 해당 기능이 포함되어 있지 않습니다.
  • 429 요청 속도를 초과했습니다(초당, 분당 또는 일일). Retry-After를 따르세요.
이 페이지가 도움이 되었나요?