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
/v1/exportsExports of the workspace, newest first. Listing and downloading are free.
Request
curl "https://api.next.toktokdata.live/v1/exports" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "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
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Create an export
/v1/exportsBuilds 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.
Request body
| Name | Type | Description |
|---|---|---|
datasetRequired | "live_sessions" | "rankings" | "watchlist" | "recruit_pipeline" | "gifters" | |
boardOptional | string | Board key for rankings, as in /v1/rankings/official. |
regionOptional | string | Region for rankings (and the creators for gifters).Default: VN |
leagueTierOptional | string | League 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
{ "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
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.402The workspace's credit wallet cannot cover the call;resetAtsays when the credits reset.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Get an export
/v1/exports/{job_id}Status and download link of one export.
Path parameters
| Name | Type | Description |
|---|---|---|
job_idRequired | string | Export id. |
Request
curl "https://api.next.toktokdata.live/v1/exports/109da4de-c958-5e53-9b3d-abd2c89b621e" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"Response
{ "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
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.
Download an export
/v1/exports/{job_id}/downloadThe file itself (text/csv or Excel), as an attachment. 409 until it is ready.
Path parameters
| Name | Type | Description |
|---|---|---|
job_idRequired | string | Export 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
400Invalid parameter or body;codenames the problem.401Missing or unknown API key.403The key lacks the scope, or the plan does not include the feature.429Request rate exceeded (per second, per minute or per day); honourRetry-After.