取得 API Key 用量

概覽

這個 endpoint 會回傳單一 API Key 維度的用量明細，同時不暴露實體 routing 中繼資料。

查詢參數

參數	型別	預設值 / 限制	說明
`page`	integer	預設 `1`，最小 `1`	從 1 開始的頁碼
`limit`	integer	預設 `50`，最小 `1`，最大 `100`	每頁筆數
`model`	string	最大長度 `100`	請求時使用的模型名稱
`modelVendor`	string	最大長度 `100`	公開模型供應商
`scene`	enum	-	`chat`, `image`, `audio`, `video`, `embedding`, `rerank`, `translation`, `music`, `3d`, `realtime`
`startDate`	string	-	起始時間（含），接受帶時區的 RFC3339 或 `YYYY-MM-DD`
`endDate`	string	-	結束時間（含），接受帶時區的 RFC3339 或 `YYYY-MM-DD`

如果同時提供 startDate 與 endDate，則 startDate 必須早於或等於 endDate。

說明

金額欄位僅支援 USD。
回應支援分頁。
回應只包含公開 billing 與 reporting 欄位。
當底層請求已完成結算時，每條用量明細還會包含 billing_transaction_id。建議將它與 request_id 一起用於請求級對帳。
內部 routing 與實體渠道中繼資料會持續被隱藏。

範例

請求

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 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

5 分鐘快取寫入 token 數。

items[].cache_write_tokens_1hnumber

1 小時快取寫入 token 數。

items[].costnumber

以 JSON 數字回傳的 USD 費用，供顯示使用。

items[].cost_decimalstring

以十進位字串回傳的 USD 精確費用。

items[].requested_policystring | null

auto, verified, official, null. 請求的交付策略；未記錄時為 null。

items[].resolved_tierstring | null

verified, official, null. 實際使用的交付層級；未記錄時為 null。

items[].charged_price_basisobject | null

實際採用的價格和計費用量；未記錄時為 null。

items[].created_atstring

用量明細的 ISO 時間戳記。

summary.total_requestsnumber

請求總數。

summary.total_costnumber

以 JSON 數字回傳的 USD 總費用，供顯示使用。

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 格式。

endDate?string

包含日期篩選器。接受帶時區的 RFC3339（例如 2026-03-28T00:00:00+08:00）或 YYYY-MM-DD 格式。

取得 API Key 用量

概覽

查詢參數

說明

範例

請求 / 回應

回應範例

重要欄位

授權

路徑參數

查詢參數

回應

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

取得 API Key 用量

概覽Copy Anchor Link

查詢參數Copy Anchor Link

說明Copy Anchor Link

範例Copy Anchor Link

請求 / 回應Copy Anchor Link

回應範例Copy Anchor Link

重要欄位Copy Anchor Link

授權Copy Anchor Link

路徑參數Copy Anchor Link

查詢參數Copy Anchor Link

回應Copy Anchor Link

200application/json

400application/json

401application/json

403application/json

404application/json

概覽

查詢參數

說明

範例

請求 / 回應

回應範例

重要欄位

授權

路徑參數

查詢參數

回應

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`