الإدارة

جلب استخدام مفتاح API

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

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

نظرة عامة

يعيد هذا الـ endpoint تفاصيل الاستخدام على مستوى مفتاح API من دون كشف بيانات التوجيه الفيزيائي.

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

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

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

ملاحظات

  • تدعم حقول المبالغ المالية الدولار الأمريكي فقط.

  • هذه الاستجابة تدعم ترقيم الصفحات.

  • لا تتضمن الاستجابة إلا حقول الفوترة والتقارير العامة.

  • قد تتضمن كل سطر usage أيضاً الحقل billing_transaction_id بعد اكتمال تسوية الطلب الأساسي. استخدمه مع request_id للمطابقة على مستوى الطلب.

  • يتم إخفاء بيانات التوجيه الداخلي والقنوات الفيزيائية عمدًا.

مثال

الطلب

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-31" \
  -H "Authorization: Bearer mt-your-management-token"

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

توفّر هذه الصفحة مخطط OpenAPI وأمثلة طلبات قابلة للنسخ. أرسل طلبات الإدارة من الطرفية أو برنامج العميل باستخدام 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-3-7-sonnet"
    ],
    "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
عدد رموز المطالبة.
items[].completion_tokensnumber
عدد رموز الإكمال.
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
السعر المطبق والكمية القابلة للفوترة، عند تسجيلهما.
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.

endDate?string

عامل تصفية التاريخ الشامل. يقبل إما RFC3339 مع المنطقة الزمنية (على سبيل المثال 2026-03-28T00:00:00+08:00) أو YYYY-MM-DD.

الاستجابة

application/json

application/json

application/json

application/json

application/json