Usage

Query your own consumption: totals, per-model and per-day breakdowns, monthly history and the raw request log. All figures come from the same metering records that drive billing, so they reconcile exactly with your ledger.

Dates are UTC calendar days in YYYY-MM-DD form. Token amounts in aggregate responses are decimal strings.

Common query parameters#

startdate: First day to include. Defaults to 30 days before end.
enddate: Last day to include (inclusive). Defaults to today.
modelstring: Restrict to one model slug or alias.
api_key_iduuid: Restrict to requests made with one API key (summary endpoint only).

Ranges may not exceed one year.

Usage summary#

GET/v1/usage

JSON

{
  "object": "usage",
  "start": "2026-08-17",
  "end": "2026-09-15",
  "requests": 12840,
  "errors": 31,
  "input_tokens": "48210044",
  "cached_input_tokens": "9022110",
  "output_tokens": "6120933",
  "reasoning_tokens": "402118",
  "total_tokens": "54330977",
  "tokens_debited": "31877422",
  "cost_usd": "63.754844",
  "avg_latency_ms": 1840,
  "by_model": [
    { "model": "claud-5.1", "requests": 9800, "input_tokens": "40012001", "output_tokens": "5010002", "tokens_debited": "26200000", "cost_usd": "52.400000" },
    { "model": "claud-flash", "requests": 3040, "input_tokens": "8198043", "output_tokens": "1110931", "tokens_debited": "5677422", "cost_usd": "11.354844" }
  ]
}

errors counts requests that failed after authentication (rate limits, upstream failures, cancelled streams). Failed requests that produced no output are not billed, so tokens_debited reflects successful work only.

Daily breakdown#

GET/v1/usage/daily

One entry per UTC day in the range, including zero days.

JSON

{
  "object": "list",
  "data": [
    { "date": "2026-09-14", "requests": 412, "errors": 1, "input_tokens": "1601122", "output_tokens": "202001", "tokens_debited": "1050000", "cost_usd": "2.100000" },
    { "date": "2026-09-15", "requests": 388, "errors": 0, "input_tokens": "1499211", "output_tokens": "190220", "tokens_debited": "990000", "cost_usd": "1.980000" }
  ]
}

Monthly history#

GET/v1/usage/monthly

monthsintegerdefault: 6: How many calendar months to return, ending with the current one. Between 1 and 24.

JSON

{
  "object": "list",
  "data": [
    { "month": "2026-08", "requests": 13120, "errors": 40, "input_tokens": "50120044", "output_tokens": "6400000", "tokens_debited": "33000000", "cost_usd": "66.000000" },
    { "month": "2026-09", "requests": 6200, "errors": 12, "input_tokens": "24010000", "output_tokens": "3000000", "tokens_debited": "15500000", "cost_usd": "31.000000" }
  ],
  "current_month_start": "2026-09-01"
}

Request log#

GET/v1/usage/requests

Individual requests, newest first. Paginate with before.

limitintegerdefault: 50: Up to 200.
beforestring: ISO-8601 timestamp; returns requests created strictly before it.

JSON

{
  "object": "list",
  "data": [
    {
      "request_id": "req_01J9X3Q5K7M2N8P4R6T0V2W4Y6",
      "model": "claud-5.1",
      "status": "success",
      "source": "api",
      "input_tokens": 63,
      "cached_input_tokens": 0,
      "output_tokens": 119,
      "reasoning_tokens": 0,
      "tokens_debited": "203",
      "cost_usd": "0.000406",
      "latency_ms": 1211,
      "stream": false,
      "finish_reason": "stop",
      "error_code": null,
      "created_at": "2026-09-15T17:39:33.071Z"
    }
  ],
  "has_more": true
}

statusstring: success, error, provider_error, rate_limited, insufficient_balance, cancelled or blocked.
sourcestring: api, chat (web chat) or playground.
error_codestring | null: The error code returned to the caller when status is not success.

Prompt and completion text is never stored on usage records; only counts and metadata are kept.

Examples#

# Last 7 days for one model
curl "https://api.claudkey.com/v1/usage?start=2026-09-08&end=2026-09-15&model=claud-5.1" \
  -H "Authorization: Bearer $CLAUD_API_KEY"