> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# 取得 API Key 用量
> 返回某個使用者 API Key 的分頁用量明細。
## 概覽
這個 endpoint 會回傳單一 API Key 維度的用量明細，同時不暴露實體 routing 中繼資料。
## Query 參數
| 參數 | 型別 | 預設值 / 限制 | 說明 |
| --------------- | ------- | ----------------------- | -------------------------------------------------------------------------------------------------- |
| `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` |
| `accessChannel` | enum | - | `platform` 或 `byok` |
| `startDate` | string | - | 起始時間（含），接受帶時區的 RFC3339 或 `YYYY-MM-DD` |
| `endDate` | string | - | 結束時間（含），接受帶時區的 RFC3339 或 `YYYY-MM-DD` |
如果同時提供 `startDate` 與 `endDate`，則 `startDate` 必須早於或等於 `endDate`。
## 說明
* 回應支援分頁。
* 回應只包含公開 billing 與 reporting 欄位。
* 當底層請求已完成結算時，每條用量明細還會包含 `billing_transaction_id`。建議將它與 `request_id` 一起用於請求級對帳。
* 內部 routing 與實體渠道中繼資料會持續被隱藏。
## 範例
```bash cURL theme={null}
curl "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456/usage?page=1&limit=20&scene=video&accessChannel=platform&startDate=2026-03-01&endDate=2026-03-31" \
-H "Authorization: Bearer mt-your-management-token"
```
## 請求 / 回應
精確 schema 與回應欄位，請使用上方的互動式 OpenAPI 面板。
## Response example
```json 200 OK theme={null}
{
"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-mini",
"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"
},
"items": [
{
"request_id": "req_abc123",
"billing_transaction_id": "billtxn_abc123",
"model": "gpt-5-mini",
"logical_model": "gpt-5-mini",
"model_vendor": "OpenAI",
"scene": "chat",
"access_channel": "platform",
"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"
}
],
"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-mini",
"logical_model": "gpt-5-mini",
"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-mini",
"logical_model": "gpt-5-mini",
"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"
}
],
"by_access_channel": [
{
"access_channel": "platform",
"requests": 1,
"cost": 0.0012
}
],
"daily_cost": [
{
"date": "2026-07-08T00:00:00.000Z",
"cost": 0.0012,
"cost_decimal": "0.0012"
}
]
}
}
```
## Important fields
API key summary using the same fields as list/create/update responses.
Paginated usage rows.
Pagination metadata with `page`, `limit`, `total`, and `totalPages`.
Aggregated totals for the selected filters.
Aggregated breakdowns for the selected filters.
Public request identifier for support and reconciliation.
Settled billing transaction id when available.
Requested public model name.
Logical public model used for reporting.
Public model vendor.
Public request scene.
`platform` or `byok`.
Billing usage unit, such as `per_token`.
Usage quantity as a JSON number for display.
Exact usage quantity as a decimal string.
Prompt token count.
Completion token count.
Total token count.
Cache read token count.
Total cache write token count.
Five-minute cache write token count.
One-hour cache write token count.
Cost in USD as a JSON number for display.
Exact cost in USD as a decimal string.
ISO usage row timestamp.
Total request count.
Total cost in USD as a JSON number for display.
Exact total cost in USD as a decimal string.
Total prompt tokens.
Total completion tokens.
Total tokens.
Usage quantity grouped by usage unit.
Breakdown by requested public model.
Breakdown by logical public model.
Breakdown by public model vendor.
Breakdown by public request scene.
Breakdown by `platform` or `byok` access channel.
Daily cost trend.