RoomScope

최종 업데이트

크리에이터

저장된 크리에이터 프로필, 변경 내역, 팔로우 관계, 분석.

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

크리에이터 검색

GET/v1/creators

핸들 또는 표시 이름의 일부로 대소문자 구분 없이 검색하며, 팔로워가 많은 순으로 반환합니다. q가 비어 있으면 저장된 전체 목록을 탐색합니다.

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

쿼리 파라미터

쿼리 파라미터 · GET /v1/creators
NameTypeDescription
qOptional
string핸들(@ 포함 또는 제외) 또는 표시 이름의 일부.
limitOptional
integer최대 결과 수. 범위 1–100.
Default: 20

요청

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

응답

200 OK
{  "data": {    "query": "linh.live",    "results": [      {        "tiktokUserId": "990000000000000001",        "uniqueId": "linh.live",        "displayName": "Linh Live",        "region": "VN",        "avatarUrl": null,        "followerCount": 123456,        "verified": true      }    ]  },  "provenance": {    "observedAt": "2026-11-01T10:36:44.935Z",    "freshness": "near_realtime",    "source": "public_creator_profile",    "sourceKind": "derived",    "coverageStatus": "observed",    "methodologyVersion": "creators-v1",    "window": null  }}

오류

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

크리에이터 프로필 조회

GET/v1/creators/{uid}

저장된 공개 프로필과 최근 카운터 기록.

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

경로 파라미터

경로 파라미터 · GET /v1/creators/{uid}
NameTypeDescription
uidRequired
string@를 제외한 크리에이터 핸들(linh.live) 또는 숫자로 된 TikTok 사용자 ID.

요청

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

응답

200 OK
{  "data": {    "creator": {      "tiktokUserId": "990000000000000001",      "uniqueId": "linh.live",      "secUid": null,      "displayName": "Linh Live",      "region": "VN",      "language": null,      "signature": "Daily LIVE from Hanoi",      "avatarUrl": null,      "followerCount": 123456,      "followingCount": 321,      "awemeCount": 3,      "totalFavorited": 9876543,      "favoritingCount": null,      "verified": true,      "customVerify": null,      "enterpriseVerifyReason": null,      "instagramId": null,      "youtubeChannelId": null,      "twitterId": null,      "firstSeenAt": "2026-10-02T10:51:44.935Z",      "lastRefreshedAt": "2026-11-01T10:36:44.935Z",      "history": []    }  },  "provenance": {    "observedAt": "2026-11-01T10:36:44.935Z",    "freshness": "near_realtime",    "source": "public_creator_profile",    "sourceKind": "derived",    "coverageStatus": "observed",    "methodologyVersion": "creators-v1",    "window": null  }}

오류

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

크리에이터의 동영상 분석

GET/v1/creators/{uid}/analysis

저장된 동영상만으로 계산한 참여도 보고서: 합계, 중앙값, 게시 주기.

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

경로 파라미터

경로 파라미터 · GET /v1/creators/{uid}/analysis
NameTypeDescription
uidRequired
string@를 제외한 크리에이터 핸들(linh.live) 또는 숫자로 된 TikTok 사용자 ID.

요청

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

응답

200 OK
{  "data": {    "creator": {      "tiktokUserId": "990000000000000001",      "uniqueId": "linh.live",      "displayName": "Linh Live",      "avatarUrl": null,      "region": "VN",      "verified": true,      "followerCount": 123456,      "followingCount": 321,      "awemeCount": 3,      "totalFavorited": 9876543,      "firstSeenAt": "2026-10-02T10:51:44.935Z",      "lastRefreshedAt": "2026-11-01T10:36:44.935Z"    },    "sample": {      "videosAnalyzed": 3,      "oldestVideoAt": "2026-10-29T10:51:44.935Z",      "newestVideoAt": "2026-10-31T10:51:44.935Z",      "spanDays": 2,      "shareOfCatalog": 1    },    "engagement": {      "totalPlays": 60000,      "totalLikes": 6000,      "totalComments": 600,      "totalShares": 0,      "avgPlays": 20000,      "medianPlays": 20000,      "avgLikes": 2000,      "avgComments": 200,      "avgShares": 0,      "engagementRate": 0.11,      "likeRate": 0.1,      "commentRate": 0.01,      "shareRate": 0,      "viewsPerFollower": 0.162    },    "cadence": {      "postsPerWeek": 7,      "avgDaysBetweenPosts": 1,      "longestGapDays": 1,      "busiestWeekday": 4,      "postsByWeekday": [        0,        0      ]    },    "topByPlays": [      {        "videoId": "7990000000000000003",        "description": "Video 3",        "createTime": "2026-10-29T10:51:44.935Z",        "playCount": 30000,        "diggCount": 3000,        "commentCount": 300,        "shareCount": null,        "engagementRate": 0.11      },      {        "videoId": "7990000000000000002",        "description": "Video 2",        "createTime": "2026-10-30T10:51:44.935Z",        "playCount": 20000,        "diggCount": 2000,        "commentCount": 200,        "shareCount": null,        "engagementRate": 0.11      }    ],    "topByEngagement": [      {        "videoId": "7990000000000000001",        "description": "Video 1",        "createTime": "2026-10-31T10:51:44.935Z",        "playCount": 10000,        "diggCount": 1000,        "commentCount": 100,        "shareCount": null,        "engagementRate": 0.11      },      {        "videoId": "7990000000000000002",        "description": "Video 2",        "createTime": "2026-10-30T10:51:44.935Z",        "playCount": 20000,        "diggCount": 2000,        "commentCount": 200,        "shareCount": null,        "engagementRate": 0.11      }    ],    "audience": null,    "growth": null,    "limits": [      {        "code": "thin-video-sample",        "message": "Only 3 video(s) analysed — too few to describe the account's typical performance."      },      {        "code": "single-observation",        "message": "This account has been observed only once, so no follower growth can be shown yet."      }    ]  },  "provenance": {    "observedAt": "2026-11-01T10:36:44.935Z",    "freshness": "near_realtime",    "source": "derived_creator_analysis",    "sourceKind": "derived",    "coverageStatus": "partial",    "methodologyVersion": "analysis-v1",    "window": null  }}

오류

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

프로필 변경 내역 목록 조회

GET/v1/creators/{uid}/changes

시간에 따라 관측된 핸들, 이름, 소개, 인증 상태 변경, 최신순.

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

경로 파라미터

경로 파라미터 · GET /v1/creators/{uid}/changes
NameTypeDescription
uidRequired
string@를 제외한 크리에이터 핸들(linh.live) 또는 숫자로 된 TikTok 사용자 ID.

쿼리 파라미터

쿼리 파라미터 · GET /v1/creators/{uid}/changes
NameTypeDescription
limitOptional
integer최대 변경 내역 수. 범위 1–200.
Default: 50

요청

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

응답

200 OK
{  "data": {    "tiktokUserId": "990000000000000001",    "uniqueId": "linh.live",    "changes": []  },  "provenance": {    "observedAt": "2026-10-02T10:51:44.935Z",    "freshness": "stale",    "source": "public_creator_profile",    "sourceKind": "derived",    "coverageStatus": "partial",    "methodologyVersion": "creators-v1",    "window": null  }}

오류

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

크리에이터의 팔로워 목록 조회

GET/v1/creators/{uid}/followers

저장된 팔로워. 팔로잉과 같은 구조입니다.

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

경로 파라미터

경로 파라미터 · GET /v1/creators/{uid}/followers
NameTypeDescription
uidRequired
string@를 제외한 크리에이터 핸들(linh.live) 또는 숫자로 된 TikTok 사용자 ID.

쿼리 파라미터

쿼리 파라미터 · GET /v1/creators/{uid}/followers
NameTypeDescription
cursorOptional
string이전 페이지의 nextCursor에서 받은 불투명 커서.
limitOptional
integer페이지당 항목 수.

요청

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

응답

200 OK
{  "data": {    "tiktokUserId": "990000000000000001",    "uniqueId": "linh.live",    "direction": "following",    "entries": [],    "nextCursor": null,    "hasMore": false,    "totalReported": null,    "storedCount": 0,    "isPrivate": false  },  "provenance": {    "observedAt": "2026-11-01T11:18:49.084Z",    "freshness": "stale",    "source": "public_follow_graph",    "sourceKind": "derived",    "coverageStatus": "not-covered",    "methodologyVersion": "follow-list-v1",    "window": null  }}

오류

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

크리에이터가 팔로우하는 계정 목록 조회

GET/v1/creators/{uid}/following

저장된 팔로우 관계. 비공개 계정은 isPrivate: true와 빈 항목을 반환합니다.

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

경로 파라미터

경로 파라미터 · GET /v1/creators/{uid}/following
NameTypeDescription
uidRequired
string@를 제외한 크리에이터 핸들(linh.live) 또는 숫자로 된 TikTok 사용자 ID.

쿼리 파라미터

쿼리 파라미터 · GET /v1/creators/{uid}/following
NameTypeDescription
cursorOptional
string이전 페이지의 nextCursor에서 받은 불투명 커서.
limitOptional
integer페이지당 항목 수.

요청

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

응답

200 OK
{  "data": {    "tiktokUserId": "990000000000000001",    "uniqueId": "linh.live",    "direction": "following",    "entries": [],    "nextCursor": null,    "hasMore": false,    "totalReported": null,    "storedCount": 0,    "isPrivate": false  },  "provenance": {    "observedAt": "2026-11-01T11:18:49.084Z",    "freshness": "stale",    "source": "public_follow_graph",    "sourceKind": "derived",    "coverageStatus": "not-covered",    "methodologyVersion": "follow-list-v1",    "window": null  }}

오류

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

크리에이터의 상위 후원자 조회

GET/v1/creators/{uid}/gifters

최근 7일 또는 30일 동안 크리에이터의 LIVE 방에서 선물한 후원자를 다이아몬드 기준으로 정렬합니다: 선물 수, 세션 수, 마지막 선물, 그리고 마지막으로 선물한 방의 크리에이터. RoomScope가 기록한 세션에서 읽으므로 커버리지는 항상 partial입니다. Pro 요금제 이상이 필요합니다.

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

경로 파라미터

경로 파라미터 · GET /v1/creators/{uid}/gifters
NameTypeDescription
uidRequired
string@를 제외한 크리에이터 핸들(linh.live) 또는 숫자로 된 TikTok 사용자 ID.

쿼리 파라미터

쿼리 파라미터 · GET /v1/creators/{uid}/gifters
NameTypeDescription
windowOptional
"7d" | "30d"7d 또는 30d.
Default: 7d
limitOptional
integer최대 행 수. 범위 …–100.
Default: 20

요청

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

응답

200 OK
{  "data": {    "creatorUid": "7012345678901234567",    "uniqueId": "linh.live",    "window": "7d",    "gifters": [      {        "gifterUserId": "6987001122334455667",        "gifterUniqueId": "minh.fan",        "gifterNickname": "Minh",        "avatarUrl": null,        "diamondTotal": 18450,        "giftCount": 312,        "sessions": 4,        "lastGiftAt": "2026-11-02T15:41:07.512Z",        "lastRoomCreator": "linh.live"      }    ]  },  "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/creators/{uid}/insights

핸들 기록, 최근 30일의 일별 다이아몬드(최신순), 일별 리그 스냅샷, 크리에이터의 LIVE 방. liveExact는 그날의 점수를 보드 초기화 시점에 읽었을 때 true이며, 그렇지 않으면 liveScore는 그날 읽은 가장 높은 점수입니다. observedCoins는 RoomScope가 크리에이터의 LIVE 세션에서 기록한 다이아몬드를 집계합니다. 변경된 핸들도 별칭 기록을 통해 계속 조회됩니다.

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

경로 파라미터

경로 파라미터 · GET /v1/creators/{uid}/insights
NameTypeDescription
uidRequired
string@를 제외한 크리에이터 핸들(linh.live) 또는 숫자로 된 TikTok 사용자 ID.

요청

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

응답

200 OK
{  "data": {    "creator": {      "uid": "6990000000000000001",      "uniqueId": "linh.live"    },    "aliases": [      {        "uniqueId": "linh.live",        "firstSeenAt": "2026-10-12T09:15:02.118Z",        "lastSeenAt": "2026-11-01T14:02:41.530Z"      },      {        "uniqueId": "linh.official",        "firstSeenAt": "2026-09-30T11:40:19.004Z",        "lastSeenAt": "2026-10-12T08:55:47.912Z"      }    ],    "daily": [      {        "boardDay": "2026-10-31",        "countryCode": "VN",        "tiktokScore": 184250,        "observedCoins": 171932,        "liveScore": 184250,        "liveExact": true,        "leagueClass": "B2"      },      {        "boardDay": "2026-10-30",        "countryCode": "VN",        "tiktokScore": 97410,        "observedCoins": null,        "liveScore": 97410,        "liveExact": false,        "leagueClass": "B2"      }    ],    "league": [      {        "day": "2026-10-31",        "leagueClass": "B2",        "leagueRank": 14,        "leagueCountry": "VN",        "followers": 412880      }    ],    "roomOwner": {      "roomId": "7432000000000000001",      "ownerUid": "6990000000000000001",      "ownerUniqueId": "linh.live",      "claimantUid": null,      "reason": "claim_confirmed",      "checkedAt": "2026-11-01T14:00:03.221Z"    }  },  "provenance": {    "observedAt": "2026-11-01T14:02:41.530Z",    "freshness": "near_realtime",    "source": "creator_analytics",    "sourceKind": "derived",    "coverageStatus": "observed",    "methodologyVersion": "creator-analytics-v1",    "window": {      "from": "2026-10-02T14:02:41.530Z",      "to": "2026-11-01T14:02:41.530Z",      "label": "30d"    }  }}

오류

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

LIVE 최적 시간 조회

GET/v1/insights/best-time

최근 windowDays일 동안 한 지역에서 기록된 LIVE 세션의 다이아몬드와 후원자-시간을 요일(0 = 월요일)과 UTC 시간대별로 보여 줍니다. 매일 다시 계산되며, 해당 지역에 기록된 데이터가 없으면 cells는 비어 있습니다.

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

쿼리 파라미터

쿼리 파라미터 · GET /v1/insights/best-time
NameTypeDescription
regionOptional
stringISO 3166-1 alpha-2 지역 코드.
Default: VN

요청

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

응답

200 OK
{  "data": {    "region": "VN",    "windowDays": 28,    "computedAt": "2026-11-01T01:00:04.870Z",    "cells": [      {        "weekday": 0,        "hour": 12,        "diamonds": 418230,        "gifterHours": 1874      },      {        "weekday": 0,        "hour": 13,        "diamonds": 652910,        "gifterHours": 2410      },      {        "weekday": 0,        "hour": 14,        "diamonds": 701455,        "gifterHours": 2689      }    ]  },  "provenance": {    "observedAt": "2026-11-01T01:00:04.870Z",    "freshness": "near_realtime",    "source": "creator_analytics",    "sourceKind": "derived",    "coverageStatus": "observed",    "methodologyVersion": "creator-analytics-v1",    "window": {      "from": "2026-10-04T01:00:04.870Z",      "to": "2026-11-01T01:00:04.870Z",      "label": "28d"    }  }}

오류

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

시간별 LIVE 현황 조회

GET/v1/insights/presence

시간대별로 해당 지역에서 추적 중인 랭킹 크리에이터 중 몇 명이 방송 중이었는지, 오래된 순.

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

쿼리 파라미터

쿼리 파라미터 · GET /v1/insights/presence
NameTypeDescription
regionOptional
stringISO 3166-1 alpha-2 지역 코드.
Default: VN
hoursOptional
integer조회할 과거 시간 수. 범위 1–168.
Default: 48

요청

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

응답

200 OK
{  "data": {    "region": "VN",    "hours": 48,    "points": [      {        "hourStart": "2026-11-01T12:00:00.000Z",        "liveCreators": 214,        "trackedCreators": 1630      },      {        "hourStart": "2026-11-01T13:00:00.000Z",        "liveCreators": 251,        "trackedCreators": 1642      },      {        "hourStart": "2026-11-01T14:00:00.000Z",        "liveCreators": 268,        "trackedCreators": 1655      }    ]  },  "provenance": {    "observedAt": "2026-11-01T14:05:01.402Z",    "freshness": "near_realtime",    "source": "creator_analytics",    "sourceKind": "derived",    "coverageStatus": "observed",    "methodologyVersion": "creator-analytics-v1",    "window": {      "from": "2026-10-30T14:05:01.402Z",      "to": "2026-11-01T14:05:01.402Z",      "label": "48h"    }  }}

오류

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