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#
{
"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": "claude-opus-5-5", "requests": 9800, "input_tokens": "40012001", "output_tokens": "5010002", "tokens_debited": "26200000", "cost_usd": "52.400000" },
{ "model": "claude-haiku-4-5", "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#
One entry per UTC day in the range, including zero days.
{
"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#
- monthsintegerdefault: 6
- How many calendar months to return, ending with the current one. Between 1 and 24.
{
"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#
Individual requests, newest first. Paginate with before.
- limitintegerdefault: 50
- Up to 200.
- beforestring
- ISO-8601 timestamp; returns requests created strictly before it.
{
"object": "list",
"data": [
{
"request_id": "req_01J9X3Q5K7M2N8P4R6T0V2W4Y6",
"model": "claude-opus-5-5",
"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,cancelledorblocked.- sourcestring
api,chat(web chat) orplayground.- error_codestring | null
- The error code returned to the caller when
statusis notsuccess.
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.claudech.com/v1/usage?start=2026-09-08&end=2026-09-15&model=claude-opus-5-5" \
-H "Authorization: Bearer $CLAUDECH_API_KEY"