آخر تحديث
ملفات التصدير
تصدير الجلسات المسجّلة بصيغتي CSV وExcel.
تُصادَق كل عملية بمفتاح API (Authorization: Bearer <key>) وتستخدم الأخطاء الغلاف المشترك الموضّح في الأخطاء. مولَّد من مستند OpenAPI الخاص بواجهة API.
عرض ملفات التصدير
/v1/exportsملفات التصدير الخاصة بمساحة العمل، من الأحدث إلى الأقدم. العرض والتنزيل مجانيان.
الطلب
curl "https://api.next.toktokdata.live/v1/exports" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"الاستجابة
{ "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.
إنشاء ملف تصدير
/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.
جسم الطلب
| 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}'الاستجابة
{ "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.
جلب ملف تصدير
/v1/exports/{job_id}حالة ملف تصدير واحد ورابط تنزيله.
معاملات المسار
| Name | Type | Description |
|---|---|---|
job_idRequired | string | معرّف ملف التصدير. |
الطلب
curl "https://api.next.toktokdata.live/v1/exports/109da4de-c958-5e53-9b3d-abd2c89b621e" \ -H "Authorization: Bearer $ROOMSCOPE_API_KEY"الاستجابة
{ "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.
تنزيل ملف تصدير
/v1/exports/{job_id}/downloadالملف نفسه (text/csv أو Excel) كمرفق. يُرجع 409 إلى أن يصبح جاهزًا.
معاملات المسار
| Name | Type | Description |
|---|---|---|
job_idRequired | string | معرّف ملف التصدير. |
الطلب
curl "https://api.next.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.