TokenLab

管理

取得 API Key 使用量

回傳使用者 API key 的分頁使用詳情。

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

概覽

回傳單一 API key 的分頁使用紀錄。

查詢參數

參數類型預設值 / 限制備註
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 (UTC 00:00)
endDatestring-包含上界;接受帶時區的 RFC3339 或 YYYY-MM-DD。僅日期格式代表該日開始的 UTC 00:00,若要包含整日,請使用下一日期或 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 架構與可複製的請求範例。請從您的終端機或客戶端使用 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 key 摘要,使用與列表/建立/更新回應相同的欄位。
itemsarray
分頁使用紀錄列。
paginationobject
包含 page、limit、total 與 totalPages 的分頁元數據。
summaryobject
所選篩選條件的彙總總計。
breakdownsobject
所選篩選條件的彙總細項。
items[].request_idstring | null
用於支援與核對的公開請求識別碼。
items[].billing_transaction_idstring | null
可用時的已結算帳單交易 ID。
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
提示詞 Token 數量。
items[].completion_tokensnumber
補全 Token 數量。
items[].total_tokensnumber
總 Token 數量。
items[].cache_read_tokensnumber
快取讀取 Token 數量。
items[].cache_write_tokensnumber
總快取寫入 Token 數量。
items[].cache_write_tokens_5mnumber
五分鐘快取寫入 Token 數量。
items[].cache_write_tokens_1hnumber
一小時快取寫入 Token 數量。
items[].costnumber
顯示用的 USD JSON 數字格式成本。
items[].cost_decimalstring
精確 USD 成本的十進位字串。
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
顯示用的 USD JSON 數字格式總成本。
summary.total_cost_decimalstring
精確 USD 總成本的十進位字串。
summary.total_prompt_tokensnumber
總提示詞 Token 數。
summary.total_completion_tokensnumber
總補全 Token 數。
summary.total_tokensnumber
總 Token 數。
summary.usage_unit_breakdownarray
按使用單位分組的使用量。
breakdowns.by_modelarray
按請求的公開模型細分。
breakdowns.by_logical_modelarray
按邏輯公開模型細分。
breakdowns.by_model_vendorarray
按公開模型供應商細分。
breakdowns.by_scenearray
按公開請求場景細分。
breakdowns.daily_costarray
每日成本趨勢。

授權

ManagementTokenAuth
AuthorizationBearer <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(代表 UTC 時間 00:00)。

endDate?string

上界(包含)。接受 RFC3339 格式並帶有時區(例如 2026-03-28T23:59:59+08:00)或 YYYY-MM-DD(代表該日 UTC 時間 00:00)。若要包含整天,請傳遞隔天的日期或該日結束時的 RFC3339 時間。

回應

application/json

application/json

application/json

application/json

application/json

application/json