RoomScope

Last updated

Creators

Stored creator profiles, changes and follow graph.

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.

Search creators

GET/v1/creators

Handle or display-name substring, case-insensitive, most-followed first. An empty q browses the stored set.

Scopecreator:readCreditsCached read

Query parameters

Query parameters of GET /v1/creators
NameTypeDescription
qOptional
stringHandle (with or without @) or part of the display name.
limitOptional
integerMaximum results. Range 1–100.
Default: 20

Request

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

Response

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",    "coverageStatus": "observed",    "methodologyVersion": "creators-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 creator profile

GET/v1/creators/{uid}

The stored public profile and its recent history of counters.

Scopecreator:readCreditsCached read

Path parameters

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

Request

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

Response

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",    "coverageStatus": "observed",    "methodologyVersion": "creators-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.

Analyse a creator's videos

GET/v1/creators/{uid}/analysis

Engagement report computed from the stored videos only: totals, medians, posting cadence.

Scopecreator:readCreditsCached read

Path parameters

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

Request

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

Response

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",    "coverageStatus": "partial",    "methodologyVersion": "analysis-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.

List profile changes

GET/v1/creators/{uid}/changes

Handle, name, bio and verification changes observed over time, newest first.

Scopecreator:readCreditsCached read

Path parameters

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

Query parameters

Query parameters of GET /v1/creators/{uid}/changes
NameTypeDescription
limitOptional
integerMaximum changes. Range 1–200.
Default: 50

Request

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

Response

200 OK
{  "data": {    "tiktokUserId": "990000000000000001",    "uniqueId": "linh.live",    "changes": []  },  "provenance": {    "observedAt": "2026-10-02T10:51:44.935Z",    "freshness": "stale",    "source": "public_creator_profile",    "coverageStatus": "partial",    "methodologyVersion": "creators-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.

List a creator's followers

GET/v1/creators/{uid}/followers

Stored followers, same shape as following.

Scopecreator:readCreditsCached read

Path parameters

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

Query parameters

Query parameters of GET /v1/creators/{uid}/followers
NameTypeDescription
cursorOptional
stringOpaque cursor from nextCursor of the previous page.
limitOptional
integerEntries per page.

Request

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

Response

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",    "coverageStatus": "not-covered",    "methodologyVersion": "follow-list-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.

List accounts a creator follows

GET/v1/creators/{uid}/following

Stored follow graph. Private accounts return isPrivate: true and no entries.

Scopecreator:readCreditsCached read

Path parameters

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

Query parameters

Query parameters of GET /v1/creators/{uid}/following
NameTypeDescription
cursorOptional
stringOpaque cursor from nextCursor of the previous page.
limitOptional
integerEntries per page.

Request

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

Response

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",    "coverageStatus": "not-covered",    "methodologyVersion": "follow-list-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?