Management
Get API Key Usage
Returns paginated usage details for a user API key.
Overview
Return paginated usage records for one API key.
Query Parameters
| Parameter | Type | Default / Limits | Notes |
|---|---|---|---|
page | integer | default 1, min 1 | 1-based page number |
limit | integer | default 50, min 1, max 100 | Page size |
model | string | max length 100 | Requested model name |
modelVendor | string | max length 100 | Public model vendor |
scene | enum | - | chat, image, audio, video, embedding, rerank, translation, music, 3d, realtime, systemone |
startDate | string | - | Inclusive lower bound; accepts RFC3339 with timezone or YYYY-MM-DD (00:00 UTC) |
endDate | string | - | Inclusive upper bound; accepts RFC3339 with timezone or YYYY-MM-DD. A date-only value means 00:00 UTC at the start of that day, so to include a whole day use the next date or an RFC3339 time |
If both startDate and endDate are present, startDate must be earlier than or equal to endDate.
Notes
-
Monetary fields are USD-only.
-
The response is paginated.
-
Settled records can include
billing_transaction_id. Save it withrequest_idwhen you need to match a charge to a request. -
Records are sorted by
created_at, newest first. -
A
429with the codereport_busymeans the report queue is full. Retry after theRetry-Afterseconds.
Request
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"Request / Response
This page provides the OpenAPI schema and copyable request examples. Send management requests from your terminal or client with a Management Token; direct sending is not available on this page.
Response
{
"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"
}
]
}
}Important fields
page, limit, total, and totalPages.per_token.auto, verified, official, null. Requested delivery policy, when recorded.verified, official, null. Delivery tier used, when recorded.measure.dimensions includes webSearchCalls or groundedPrompts, and effectiveUnitPrices includes the price of each call as webSearch or groundedPrompt.Authorization
ManagementTokenAuth Management token authentication. Create or manage Management Tokens in Dashboard > API > Management Tokens.
In: header
Path Parameters
Query Parameters
1-based page number. Default is 1.
1 <= value1Page size. Default is 50 and the maximum is 100.
1 <= value <= 10050Filter by requested model name. Maximum length 100.
length <= 100Filter by public model vendor. Maximum length 100.
length <= 100Filter by public request scene.
Value in
- "chat"
- "image"
- "audio"
- "video"
- "embedding"
- "rerank"
- "translation"
- "music"
- "3d"
- "realtime"
- "systemone"
Lower bound, inclusive. Accepts RFC3339 with timezone (for example 2026-03-28T00:00:00+08:00) or YYYY-MM-DD, which means 00:00 UTC.
Upper bound, inclusive. Accepts RFC3339 with timezone (for example 2026-03-28T23:59:59+08:00) or YYYY-MM-DD, which means 00:00 UTC at the start of that day. To include a whole day, pass the next day's date or an RFC3339 time at the end of the day.
Response
application/json
application/json
application/json
application/json
application/json
application/json