Skip to main content

​
Overview

This endpoint returns consumption-only billing aggregates for the selected API key, including total cost, total requests, usage unit breakdowns, and breakdowns by requested model name (model), vendor, scene, accessChannel, cache class, plus a daily cost trend.

​
Notes

  • Monetary fields are USD-only. CNY inputs are retired and return 400 currency_retired.
  • Recharge, invoices, and other organization-level financial records are intentionally excluded.

​
Example

curl -X GET "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456/billing?startDate=2026-01-01&endDate=2026-01-31" \
  -H "Authorization: Bearer mt-your-management-token"

​
Request / Response

Use the interactive OpenAPI panel above for the exact schema.

​
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"
  },
  "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
object
API key summary using the same fields as list/create/update responses.
​
summary
object
Aggregated totals for the selected filters.
​
breakdowns
object
Aggregated breakdowns for the selected filters.
​
summary.total_requests
number
Total request count.
​
summary.total_cost
number
Total cost in USD as a JSON number for display.
​
summary.total_cost_decimal
string
Exact total cost in USD as a decimal string.
​
summary.total_prompt_tokens
number
Total prompt tokens.
​
summary.total_completion_tokens
number
Total completion tokens.
​
summary.total_tokens
number
Total tokens.
​
summary.usage_unit_breakdown
array
Usage quantity grouped by usage unit.
​
breakdowns.by_model
array
Breakdown by requested public model.
​
breakdowns.by_logical_model
array
Breakdown by logical public model.
​
breakdowns.by_model_vendor
array
Breakdown by public model vendor.
​
breakdowns.by_scene
array
Breakdown by public request scene.
​
breakdowns.by_access_channel
array
Breakdown by platform or byok access channel.
​
breakdowns.daily_cost
array
Daily cost trend.