Get API Key Usage

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`
`startDate`	string	-	Inclusive lower bound; accepts RFC3339 with timezone or `YYYY-MM-DD`
`endDate`	string	-	Inclusive upper bound; accepts RFC3339 with timezone or `YYYY-MM-DD`

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 with request_id when you need to match a charge to a request.

Example

Request

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"

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 example

Response

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"
      }
    ]
  }
}

Important fields

api_keyobject

API key summary using the same fields as list/create/update responses.

itemsarray

Paginated usage rows.

paginationobject

Pagination metadata with page, limit, total, and totalPages.

summaryobject

Aggregated totals for the selected filters.

breakdownsobject

Aggregated breakdowns for the selected filters.

items[].request_idstring | null

Public request identifier for support and reconciliation.

items[].billing_transaction_idstring | null

Settled billing transaction id when available.

items[].modelstring

Requested public model name.

items[].logical_modelstring

Logical public model used for reporting.

items[].model_vendorstring | null

Public model vendor.

items[].scenestring | null

Public request scene.

items[].usage_unitstring

Billing usage unit, such as per_token.

items[].usage_quantitynumber

Usage quantity as a JSON number for display.

items[].usage_quantity_decimalstring

Exact usage quantity as a decimal string.

items[].prompt_tokensnumber

Prompt token count.

items[].completion_tokensnumber

Completion token count.

items[].total_tokensnumber

Total token count.

items[].cache_read_tokensnumber

Cache read token count.

items[].cache_write_tokensnumber

Total cache write token count.

items[].cache_write_tokens_5mnumber

Five-minute cache write token count.

items[].cache_write_tokens_1hnumber

One-hour cache write token count.

items[].costnumber

Cost in USD as a JSON number for display.

items[].cost_decimalstring

Exact cost in USD as a decimal string.

items[].requested_policystring | null

auto, verified, official, null. Requested delivery policy, when recorded.

items[].resolved_tierstring | null

verified, official, null. Delivery tier used, when recorded.

items[].charged_price_basisobject | null

Applied price and billable quantity, when recorded.

items[].created_atstring

ISO usage row timestamp.

summary.total_requestsnumber

Total request count.

summary.total_costnumber

Total cost in USD as a JSON number for display.

summary.total_cost_decimalstring

Exact total cost in USD as a decimal string.

summary.total_prompt_tokensnumber

Total prompt tokens.

summary.total_completion_tokensnumber

Total completion tokens.

summary.total_tokensnumber

Total tokens.

summary.usage_unit_breakdownarray

Usage quantity grouped by usage unit.

breakdowns.by_modelarray

Breakdown by requested public model.

breakdowns.by_logical_modelarray

Breakdown by logical public model.

breakdowns.by_model_vendorarray

Breakdown by public model vendor.

breakdowns.by_scenearray

Breakdown by public request scene.

breakdowns.daily_costarray

Daily cost trend.

Authorization

ManagementTokenAuth

AuthorizationBearer <token>

Management token authentication. Create or manage Management Tokens in Dashboard > API > Management Tokens.

In: header

Path Parameters

keyId*string

Query Parameters

page?integer

1-based page number. Default is 1.

Range1 <= value

default1

limit?integer

Page size. Default is 50 and the maximum is 100.

Range1 <= value <= 100

default50

model?string

Filter by requested model name. Maximum length 100.

Lengthlength <= 100

modelVendor?string

Filter by public model vendor. Maximum length 100.

Lengthlength <= 100

scene?string

Filter by public request scene.

Value in

"chat"
"image"
"audio"
"video"
"embedding"
"rerank"
"translation"
"music"
"3d"
"realtime"
"systemone"

startDate?string

Inclusive date filter. Accepts either RFC3339 with timezone (for example 2026-03-28T00:00:00+08:00) or YYYY-MM-DD.

endDate?string

Inclusive date filter. Accepts either RFC3339 with timezone (for example 2026-03-28T00:00:00+08:00) or YYYY-MM-DD.

Get API Key Usage

Overview

Query Parameters

Notes

Example

Request / Response

Response example

Important fields

Authorization

Path Parameters

Query Parameters

Response

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Get API Key Usage

OverviewCopy Anchor Link

Query ParametersCopy Anchor Link

NotesCopy Anchor Link

ExampleCopy Anchor Link

Request / ResponseCopy Anchor Link

Response exampleCopy Anchor Link

Important fieldsCopy Anchor Link

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Query ParametersCopy Anchor Link

ResponseCopy Anchor Link

200application/json

400application/json

401application/json

403application/json

404application/json

Overview

Query Parameters

Notes

Example

Request / Response

Response example

Important fields

Authorization

Path Parameters

Query Parameters

Response

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`