最後更新
匯出
已記錄場次的 CSV 與 Excel 匯出。
所有操作都以 API 金鑰進行身分驗證 (Authorization: Bearer <key>) ;錯誤一律使用共通的錯誤格式,說明請見 錯誤. 本頁由 API 的 OpenAPI 文件產生。
列出匯出檔
GET
/v1/exports工作區的匯出檔,由新到舊排列。列出與下載都免費。
權限範圍export點數免費
請求
curl "https://api.next.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會指出問題所在。401API 金鑰缺少或不存在。403金鑰缺少該權限範圍,或方案未包含此功能。429超過請求速率(每秒、每分鐘或每日);請遵守Retry-After。
建立匯出檔
POST
/v1/exports建立資料集:live_sessions(區間內追蹤的場次)、rankings(依您的方案所見的一份官方排行榜,遮蔽的列仍保持遮蔽;需要 rank:read)、gifters(已記錄直播間的送禮者;rangeDays 不超過 7 時為 7 天,否則為 30 天;可選 region;需要 gifter:read 與 Pro 方案)、watchlist 或 recruit_pipeline(招募標記,Pro 方案起提供;兩者皆僅限已登入的工作階段)。1,000 列以內作業會以 ready(201)回傳;超過則為 pending(202)並在背景建立:持續查詢直到 ready。每個檔案都附有來源:CSV 每列結尾為 source、observed_at、coverage_status 與 methodology,活頁簿另加 Provenance 工作表。只有以 API 金鑰建立時才收費。
權限範圍export點數匯出
請求主體
| Name | Type | Description |
|---|---|---|
datasetRequired | "live_sessions" | "rankings" | "watchlist" | "recruit_pipeline" | "gifters" | |
boardOptional | string | rankings 的榜單鍵,與 /v1/rankings/official 相同。 |
regionOptional | string | rankings 的地區(以及 gifters 的受贈創作者地區)。Default: VN |
leagueTierOptional | string | rankings 的聯賽級別篩選(A1 至 D5)。 |
formatRequired | "csv" | "xlsx" | xlsx 需要包含 Excel 的方案。 |
rangeDaysOptional | integer | Default: 30 |
請求
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}'回應
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會指出問題所在。401API 金鑰缺少或不存在。402工作區的點數錢包不足以支付此呼叫;resetAt表示點數重置的時間。403金鑰缺少該權限範圍,或方案未包含此功能。429超過請求速率(每秒、每分鐘或每日);請遵守Retry-After。
取得匯出檔
GET
/v1/exports/{job_id}單一匯出檔的狀態與下載連結。
權限範圍export點數免費
路徑參數
| Name | Type | Description |
|---|---|---|
job_idRequired | string | 匯出檔 ID。 |
請求
curl "https://api.next.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會指出問題所在。401API 金鑰缺少或不存在。403金鑰缺少該權限範圍,或方案未包含此功能。429超過請求速率(每秒、每分鐘或每日);請遵守Retry-After。
下載匯出檔
GET
/v1/exports/{job_id}/download檔案本身(text/csv 或 Excel),以附件形式傳回。就緒前回傳 409。
權限範圍export點數免費
路徑參數
| Name | Type | Description |
|---|---|---|
job_idRequired | string | 匯出檔 ID。 |
請求
curl "https://api.next.toktokdata.live/v1/exports/109da4de-c958-5e53-9b3d-abd2c89b621e/download" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"回應
200 回應,並以附件形式傳回檔案。
錯誤
400參數或請求主體無效;code會指出問題所在。401API 金鑰缺少或不存在。403金鑰缺少該權限範圍,或方案未包含此功能。429超過請求速率(每秒、每分鐘或每日);請遵守Retry-After。
這個頁面對你有幫助嗎?