RoomScope

最後更新

匯出

已記錄場次的 CSV 與 Excel 匯出。

所有操作都以 API 金鑰進行身分驗證 (Authorization: Bearer <key>) ；錯誤一律使用共通的錯誤格式，說明請見 錯誤. 本頁由 API 的 OpenAPI 文件產生。

列出匯出檔

GET/v1/exports

工作區的匯出檔，由新到舊排列。列出與下載都免費。

權限範圍export點數免費

請求

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

回應

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

錯誤

  • 400 參數或請求主體無效；code 會指出問題所在。
  • 401 API 金鑰缺少或不存在。
  • 403 金鑰缺少該權限範圍，或方案未包含此功能。
  • 429 超過請求速率；請遵守 Retry-After。

建立匯出檔

POST/v1/exports

立即產生資料集（適用於小範圍），並回傳可供下載的工作。

權限範圍export點數匯出

請求主體

請求主體 · POST /v1/exports
NameTypeDescription
datasetRequired
"live_sessions"
formatRequired
"csv" | "xlsx"xlsx 需要包含 Excel 的方案。
rangeDaysOptional
integer
Default: 30

請求

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

回應

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

錯誤

  • 400 參數或請求主體無效；code 會指出問題所在。
  • 401 API 金鑰缺少或不存在。
  • 402 工作區的點數錢包不足以支付此呼叫；resetAt 表示點數重置的時間。
  • 403 金鑰缺少該權限範圍，或方案未包含此功能。
  • 429 超過請求速率；請遵守 Retry-After。

取得匯出檔

GET/v1/exports/{job_id}

單一匯出檔的狀態與下載連結。

權限範圍export點數免費

路徑參數

路徑參數 · GET /v1/exports/{job_id}
NameTypeDescription
job_idRequired
string匯出檔 ID。

請求

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

回應

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

錯誤

  • 400 參數或請求主體無效；code 會指出問題所在。
  • 401 API 金鑰缺少或不存在。
  • 403 金鑰缺少該權限範圍，或方案未包含此功能。
  • 429 超過請求速率；請遵守 Retry-After。

下載匯出檔

GET/v1/exports/{job_id}/download

檔案本身（text/csv 或 Excel），以附件形式傳回。就緒前回傳 409。

權限範圍export點數免費

路徑參數

路徑參數 · GET /v1/exports/{job_id}/download
NameTypeDescription
job_idRequired
string匯出檔 ID。

請求

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

回應

200 回應，並以附件形式傳回檔案。

錯誤

  • 400 參數或請求主體無效；code 會指出問題所在。
  • 401 API 金鑰缺少或不存在。
  • 403 金鑰缺少該權限範圍，或方案未包含此功能。
  • 429 超過請求速率；請遵守 Retry-After。
這個頁面對你有幫助嗎？