Get API Key Usage

curl "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456/usage?page=1&limit=20&scene=video&startDate=2026-03-01&endDate=2026-03-31" \
  -H "Authorization: Bearer mt-your-management-token"

{
  "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",
      "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"
      }
    ],
    "daily_cost": [
      {
        "date": "2026-07-08T00:00:00.000Z",
        "cost": 0.0012,
        "cost_decimal": "0.0012"
      }
    ]
  }
}

Overview

This endpoint returns key-level usage details without exposing provider-specific execution details.

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. CNY inputs are retired and return 400 currency_retired.
The response is paginated.
The response includes public billing and reporting fields only.
Each usage item can include billing_transaction_id after the underlying request reaches settled billing state. Use it together with request_id for request-level reconciliation.
Provider execution details are intentionally hidden from public management responses.

Example

curl "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456/usage?page=1&limit=20&scene=video&startDate=2026-03-01&endDate=2026-03-31" \
  -H "Authorization: Bearer mt-your-management-token"

Request / Response

Use the interactive OpenAPI panel above for the exact schema and response fields.

Response example

{
  "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",
      "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"
      }
    ],
    "daily_cost": [
      {
        "date": "2026-07-08T00:00:00.000Z",
        "cost": 0.0012,
        "cost_decimal": "0.0012"
      }
    ]
  }
}

Important fields

object

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

array

Paginated usage rows.

object

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

object

Aggregated totals for the selected filters.

object

Aggregated breakdowns for the selected filters.

string | null

Public request identifier for support and reconciliation.

string | null

Settled billing transaction id when available.

string

Requested public model name.

string

Logical public model used for reporting.

string | null

Public model vendor.

string | null

Public request scene.

string

Billing usage unit, such as per_token.

number

Usage quantity as a JSON number for display.

string

Exact usage quantity as a decimal string.

number

Prompt token count.

number

Completion token count.

number

Total token count.

number

Cache read token count.

number

Total cache write token count.

number

Five-minute cache write token count.

number

One-hour cache write token count.

number

Cost in USD as a JSON number for display.

string

Exact cost in USD as a decimal string.

string

ISO usage row timestamp.

number

Total request count.

number

Total cost in USD as a JSON number for display.

string

Exact total cost in USD as a decimal string.

number

Total prompt tokens.

number

Total completion tokens.

number

Total tokens.

array

Usage quantity grouped by usage unit.

array

Breakdown by requested public model.

array

Breakdown by logical public model.

array

Breakdown by public model vendor.

array

Breakdown by public request scene.

array

Daily cost trend.

Core

Text

Files & Batches

Images

Audio & Realtime

Music

Video & Materials

Worlds

3D

Async Jobs

Gemini Native

Management

Get API Key Usage

Overview

Query Parameters

Notes

Example

Request / Response

Response example

Important fields

​Overview

​Query Parameters

​Notes

​Example

​Request / Response

​Response example

​Important fields

Overview

Query Parameters

Notes

Example

Request / Response

Response example

Important fields