RoomScope

Last updated

Exports

CSV and Excel exports of recorded sessions.

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.

List exports

GET/v1/exports

Exports of the workspace, newest first. Listing and downloading are free.

ScopeexportCreditsFree

Request

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

Response

200 OK
{  "items": [    {      "id": "7d59b188-dc23-4ac5-908f-a3a7aaf89f36",      "dataset": "live_sessions",      "format": "csv",      "status": "ready",      "rowCount": 2,      "filename": "roomscope-live_sessions-2026-11-01.csv",      "downloadUrl": "/v1/exports/7d59b188-dc23-4ac5-908f-a3a7aaf89f36/download",      "error": null,      "createdAt": "2026-11-01T11:15:45.241Z",      "completedAt": "2026-11-01T11:15:45.240Z"    },    {      "id": "a57ddf61-5f71-4fce-82d2-8d50941e0941",      "dataset": "live_sessions",      "format": "csv",      "status": "ready",      "rowCount": 2,      "filename": "roomscope-live_sessions-2026-11-01.csv",      "downloadUrl": "/v1/exports/a57ddf61-5f71-4fce-82d2-8d50941e0941/download",      "error": null,      "createdAt": "2026-11-01T11:11:46.114Z",      "completedAt": "2026-11-01T11:11:46.113Z"    }  ],  "provenance": {    "observedAt": "2026-11-01T11:15:45.240Z",    "freshness": "near_realtime",    "source": "workspace_exports",    "sourceKind": "derived",    "coverageStatus": "observed",    "methodologyVersion": "exports-v1",    "window": null  }}

Errors

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded (per second, per minute or per day); honour Retry-After.

Create an export

POST/v1/exports

Builds a dataset: live_sessions (the followed sessions in the range), rankings (one official board as your plan sees it, masked rows stay masked; needs rank:read), gifters (the gifters of the recorded rooms, rangeDays up to 7 for 7 days else 30, optional region; needs gifter:read and the Pro plan), watchlist or recruit_pipeline (the recruit marks, from the Pro plan; both signed-in sessions only). Up to 1,000 rows the job comes back ready (201); above that it is pending (202) and is built in the background: poll it until ready. Every file carries its provenance: CSV rows end with source, observed_at, coverage_status and methodology, a workbook adds a Provenance sheet. Charged only when an API key creates it.

ScopeexportCreditsExport

Request body

Request body · POST /v1/exports
NameTypeDescription
datasetRequired
"live_sessions" | "rankings" | "watchlist" | "recruit_pipeline" | "gifters"
boardOptional
stringBoard key for rankings, as in /v1/rankings/official.
regionOptional
stringRegion for rankings (and the creators for gifters).
Default: VN
leagueTierOptional
stringLeague tier filter for rankings (A1 to D5).
formatRequired
"csv" | "xlsx"xlsx needs a plan that includes Excel.
rangeDaysOptional
integer
Default: 30

Request

curl -X POST "https://api.next.toktokdata.live/v1/exports" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY" \  -H "Content-Type: application/json" \  -d '{"dataset":"live_sessions","format":"csv","rangeDays":30}'

Response

201 Created
{  "id": "7d59b188-dc23-4ac5-908f-a3a7aaf89f36",  "dataset": "live_sessions",  "format": "csv",  "status": "ready",  "rowCount": 2,  "filename": "roomscope-live_sessions-2026-11-01.csv",  "downloadUrl": "/v1/exports/7d59b188-dc23-4ac5-908f-a3a7aaf89f36/download",  "error": null,  "createdAt": "2026-11-01T11:15:45.241Z",  "completedAt": "2026-11-01T11:15:45.240Z"}

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; resetAt says when the credits reset.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded (per second, per minute or per day); honour Retry-After.

Get an export

GET/v1/exports/{job_id}

Status and download link of one export.

ScopeexportCreditsFree

Path parameters

Path parameters · GET /v1/exports/{job_id}
NameTypeDescription
job_idRequired
stringExport id.

Request

curl "https://api.next.toktokdata.live/v1/exports/109da4de-c958-5e53-9b3d-abd2c89b621e" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Response

200 OK
{  "id": "109da4de-c958-5e53-9b3d-abd2c89b621e",  "dataset": "live_sessions",  "format": "csv",  "status": "ready",  "rowCount": 2,  "filename": "roomscope-live_sessions-2026-11-01.csv",  "downloadUrl": "/v1/exports/109da4de-c958-5e53-9b3d-abd2c89b621e/download",  "error": null,  "createdAt": "2026-11-01T09:51:44.935Z",  "completedAt": "2026-11-01T09:51:44.935Z",  "provenance": {    "observedAt": "2026-11-01T09:51:44.935Z",    "freshness": "near_realtime",    "source": "workspace_exports",    "sourceKind": "derived",    "coverageStatus": "observed",    "methodologyVersion": "exports-v1",    "window": null  }}

Errors

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded (per second, per minute or per day); honour Retry-After.

Download an export

GET/v1/exports/{job_id}/download

The file itself (text/csv or Excel), as an attachment. 409 until it is ready.

ScopeexportCreditsFree

Path parameters

Path parameters · GET /v1/exports/{job_id}/download
NameTypeDescription
job_idRequired
stringExport id.

Request

curl "https://api.next.toktokdata.live/v1/exports/109da4de-c958-5e53-9b3d-abd2c89b621e/download" \  -H "Authorization: Bearer $ROOMSCOPE_API_KEY"

Response

200 with the file as an attachment.

Errors

  • 400 Invalid parameter or body; code names the problem.
  • 401 Missing or unknown API key.
  • 403 The key lacks the scope, or the plan does not include the feature.
  • 429 Request rate exceeded (per second, per minute or per day); honour Retry-After.
Was this page helpful?