> ## 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 単位の使用量明細を返します。
## Query パラメータ
| パラメータ | 型 | 既定値 / 制約 | 説明 |
| --------------- | ------- | ------------------------ | -------------------------------------------------------------------------------------------------- |
| `page` | integer | 既定値 `1`、最小 `1` | 1 始まりのページ番号 |
| `limit` | integer | 既定値 `50`、最小 `1`、最大 `100` | 1 ページあたりの件数 |
| `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 項目のみが含まれます。
* 基になるリクエストの課金精算が完了すると、各 usage 明細に `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.