الإدارة

الحصول على استخدام مفتاح API

إرجاع تفاصيل الاستخدام المصفحة لمفتاح API الخاص بالمستخدم.

GEThttps://api.tokenlab.sh/v1/management/api-keys/{keyId}/usage

نظرة عامة

إرجاع سجلات الاستخدام المصفحة لمفتاح API واحد.

معاملات الاستعلام (Query Parameters)

المعاملالنوعالافتراضي / الحدودملاحظات
pageintegerالافتراضي 1، الحد الأدنى 1رقم الصفحة يبدأ من 1
limitintegerالافتراضي 50، الحد الأدنى 1، الحد الأقصى 100حجم الصفحة
modelstringالحد الأقصى للطول 100اسم النموذج المطلوب
modelVendorstringالحد الأقصى للطول 100مزود النموذج العام
sceneenum-chat, image, audio, video, embedding, rerank, translation, music, 3d, realtime, systemone
startDatestring-الحد الأدنى الشامل؛ يقبل تنسيق RFC3339 مع المنطقة الزمنية أو YYYY-MM-DD (00:00 بالتوقيت العالمي المنسق UTC)
endDatestring-الحد الأقصى الشامل؛ يقبل تنسيق RFC3339 مع المنطقة الزمنية أو YYYY-MM-DD. تعني القيمة التي تمثل تاريخاً فقط 00:00 بالتوقيت العالمي المنسق UTC في بداية ذلك اليوم، لذا لتضمين يوم كامل استخدم التاريخ التالي أو وقت بتنسيق RFC3339

إذا تم توفير كل من startDate و endDate، يجب أن يكون startDate أقدم من أو مساوياً لـ endDate.

ملاحظات

  • الحقول النقدية هي بالدولار الأمريكي (USD) فقط.

  • الاستجابة مصفحة.

  • يمكن أن تتضمن السجلات المستقرة billing_transaction_id. احفظه مع request_id عندما تحتاج إلى مطابقة رسوم مع طلب ما.

  • يتم فرز السجلات حسب created_at، الأحدث أولاً.

  • رمز الخطأ 429 مع الكود report_busy يعني أن قائمة انتظار التقارير ممتلئة. أعد المحاولة بعد عدد الثواني المحدد في Retry-After.

مثال

الطلب

cURL
curl "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456/usage?page=1&limit=20&scene=chat&startDate=2026-07-01&endDate=2026-07-31T23:59:59Z" \
  -H "Authorization: Bearer mt-your-management-token"

الطلب / الاستجابة

توفر هذه الصفحة مخطط OpenAPI وأمثلة طلبات قابلة للنسخ. أرسل طلبات الإدارة من جهازك الطرفي (terminal) أو عميلك باستخدام Management Token؛ الإرسال المباشر غير متاح في هذه الصفحة.

الاستجابة

200 OK
{
  "api_key": {
    "id": "key_abc123def456",
    "name": "Backend Worker",
    "key_prefix": "sk-live...",
    "status": "active",
    "limit_amount": 500,
    "limit_amount_decimal": "500",
    "used_amount": 148.25,
    "used_amount_decimal": "148.25",
    "models": [
      "gpt-5.6-luna",
      "claude-sonnet-4-6"
    ],
    "expires_at": "2026-12-31T23:59:59.000Z",
    "last_used_at": "2026-07-08T03:12:45.000Z",
    "created_at": "2026-07-01T10:00:00.000Z",
    "delivery_policy": null
  },
  "items": [
    {
      "request_id": "req_abc123",
      "billing_transaction_id": "billtxn_abc123",
      "model": "gpt-5.6-luna",
      "logical_model": "gpt-5.6-luna",
      "model_vendor": "OpenAI",
      "scene": "chat",
      "usage_unit": "per_token",
      "usage_quantity": 1500,
      "usage_quantity_decimal": "1500",
      "prompt_tokens": 1000,
      "completion_tokens": 500,
      "total_tokens": 1500,
      "cache_read_tokens": 0,
      "cache_write_tokens": 0,
      "cache_write_tokens_5m": 0,
      "cache_write_tokens_1h": 0,
      "cost": 0.0012,
      "cost_decimal": "0.0012",
      "created_at": "2026-07-08T03:15:00.000Z",
      "requested_policy": null,
      "resolved_tier": null,
      "charged_price_basis": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  },
  "summary": {
    "total_requests": 1,
    "total_cost": 0.0012,
    "total_cost_decimal": "0.0012",
    "total_prompt_tokens": 1000,
    "total_completion_tokens": 500,
    "total_tokens": 1500,
    "usage_unit_breakdown": [
      {
        "usage_unit": "per_token",
        "usage_quantity": 1500
      }
    ]
  },
  "breakdowns": {
    "by_model": [
      {
        "model": "gpt-5.6-luna",
        "logical_model": "gpt-5.6-luna",
        "model_vendor": "OpenAI",
        "requests": 1,
        "cost": 0.0012,
        "cost_decimal": "0.0012",
        "usage_quantity": 1500,
        "usage_quantity_decimal": "1500"
      }
    ],
    "by_logical_model": [
      {
        "model": "gpt-5.6-luna",
        "logical_model": "gpt-5.6-luna",
        "model_vendor": "OpenAI",
        "requests": 1,
        "cost": 0.0012,
        "cost_decimal": "0.0012",
        "usage_quantity": 1500,
        "usage_quantity_decimal": "1500"
      }
    ],
    "by_model_vendor": [
      {
        "model_vendor": "OpenAI",
        "requests": 1,
        "cost": 0.0012
      }
    ],
    "by_scene": [
      {
        "scene": "chat",
        "requests": 1,
        "cost": 0.0012,
        "cost_decimal": "0.0012"
      }
    ],
    "daily_cost": [
      {
        "date": "2026-07-08T00:00:00.000Z",
        "cost": 0.0012,
        "cost_decimal": "0.0012"
      }
    ]
  }
}

حقول هامة

api_keyobject
ملخص مفتاح API باستخدام نفس حقول استجابات القائمة/الإنشاء/التحديث.
itemsarray
صفوف الاستخدام المصفحة.
paginationobject
بيانات وصفية للترقيم تحتوي على page و limit و total و totalPages.
summaryobject
الإجماليات المجمعة للفلاتر المحددة.
breakdownsobject
التفاصيل المجمعة للفلاتر المحددة.
items[].request_idstring | null
معرف الطلب العام للدعم والمطابقة.
items[].billing_transaction_idstring | null
معرف معاملة الفوترة المستقرة عند توفره.
items[].modelstring
اسم النموذج العام المطلوب.
items[].logical_modelstring
النموذج العام المنطقي المستخدم لإعداد التقارير.
items[].model_vendorstring | null
مزود النموذج العام.
items[].scenestring | null
مشهد الطلب العام.
items[].usage_unitstring
وحدة استخدام الفوترة، مثل per_token.
items[].usage_quantitynumber
كمية الاستخدام كرقم JSON للعرض.
items[].usage_quantity_decimalstring
كمية الاستخدام الدقيقة كسلسلة نصية عشرية.
items[].prompt_tokensnumber
عدد رموز المطالبة (prompt tokens).
items[].completion_tokensnumber
عدد رموز الإكمال (completion tokens).
items[].total_tokensnumber
إجمالي عدد الرموز.
items[].cache_read_tokensnumber
عدد رموز قراءة ذاكرة التخزين المؤقت.
items[].cache_write_tokensnumber
إجمالي عدد رموز كتابة ذاكرة التخزين المؤقت.
items[].cache_write_tokens_5mnumber
عدد رموز كتابة ذاكرة التخزين المؤقت لمدة خمس دقائق.
items[].cache_write_tokens_1hnumber
عدد رموز كتابة ذاكرة التخزين المؤقت لمدة ساعة واحدة.
items[].costnumber
التكلفة بالدولار الأمريكي كرقم JSON للعرض.
items[].cost_decimalstring
التكلفة الدقيقة بالدولار الأمريكي كسلسلة نصية عشرية.
items[].requested_policystring | null
auto, verified, official, null. سياسة التسليم المطلوبة، عند تسجيلها.
items[].resolved_tierstring | null
verified, official, null. مستوى التسليم المستخدم، عند تسجيله.
items[].charged_price_basisobject | null
السعر المطبق والكمية القابلة للفوترة، عند تسجيلها. بالنسبة لطلب يحتوي على رسوم أدوات، تتضمن measure.dimensions كلاً من webSearchCalls أو groundedPrompts، وتتضمن effectiveUnitPrices سعر كل استدعاء كـ webSearch أو groundedPrompt.
items[].created_atstring
الطابع الزمني لصف الاستخدام بتنسيق ISO.
summary.total_requestsnumber
إجمالي عدد الطلبات.
summary.total_costnumber
إجمالي التكلفة بالدولار الأمريكي كرقم JSON للعرض.
summary.total_cost_decimalstring
إجمالي التكلفة الدقيقة بالدولار الأمريكي كسلسلة نصية عشرية.
summary.total_prompt_tokensnumber
إجمالي رموز المطالبة.
summary.total_completion_tokensnumber
إجمالي رموز الإكمال.
summary.total_tokensnumber
إجمالي الرموز.
summary.usage_unit_breakdownarray
كمية الاستخدام مجمعة حسب وحدة الاستخدام.
breakdowns.by_modelarray
تفصيل حسب النموذج العام المطلوب.
breakdowns.by_logical_modelarray
تفصيل حسب النموذج العام المنطقي.
breakdowns.by_model_vendorarray
تفصيل حسب مزود النموذج العام.
breakdowns.by_scenearray
تفصيل حسب مشهد الطلب العام.
breakdowns.daily_costarray
اتجاه التكلفة اليومية.

التفويض

ManagementTokenAuth
AuthorizationBearer <token>

مصادقة رمز الإدارة (Management token). قم بإنشاء أو إدارة رموز الإدارة في Dashboard > API > Management Tokens.

الموضع: header

معاملات المسار

keyId*string

معاملات الاستعلام

page?integer

رقم الصفحة يبدأ من 1. الافتراضي هو 1.

النطاق1 <= value
الافتراضي1
limit?integer

حجم الصفحة. الافتراضي هو 50 والحد الأقصى هو 100.

النطاق1 <= value <= 100
الافتراضي50
model?string

التصفية حسب اسم النموذج المطلوب. الحد الأقصى للطول 100.

الطولlength <= 100
modelVendor?string

التصفية حسب مزود النموذج العام. الحد الأقصى للطول 100.

الطولlength <= 100
scene?string

التصفية حسب مشهد الطلب العام.

القيم المتاحة

  • "chat"
  • "image"
  • "audio"
  • "video"
  • "embedding"
  • "rerank"
  • "translation"
  • "music"
  • "3d"
  • "realtime"
  • "systemone"
startDate?string

الحد الأدنى، شامل. يقبل تنسيق RFC3339 مع المنطقة الزمنية (على سبيل المثال 2026-03-28T00:00:00+08:00) أو YYYY-MM-DD، والذي يعني 00:00 بالتوقيت العالمي المنسق (UTC).

endDate?string

الحد الأعلى، شامل. يقبل تنسيق RFC3339 مع المنطقة الزمنية (على سبيل المثال 2026-03-28T23:59:59+08:00) أو YYYY-MM-DD، والذي يعني 00:00 بالتوقيت العالمي المنسق (UTC) في بداية ذلك اليوم. لتضمين يوم كامل، مرر تاريخ اليوم التالي أو وقت RFC3339 في نهاية اليوم.

الاستجابة

application/json

application/json

application/json

application/json

application/json

application/json