> ## 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 的分页用量明细。
## 概览
该接口返回单个 API Key 维度的分页用量明细，不暴露提供商执行细节。
## Query 参数
| 参数 | 类型 | 默认值 / 限制 | 说明 |
| --------------- | ------- | ----------------------- | -------------------------------------------------------------------------------------------------- |
| `page` | integer | 默认 `1`，最小 `1` | 1-based 页码 |
| `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_transaction_id`。建议将它与 `request_id` 一起用于请求级对账。
* 供应商执行细节会被隐藏。
## 示例
```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.