# 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

- `start` (date): First day to include. Defaults to 30 days before `end`.
- `end` (date): Last day to include (inclusive). Defaults to today.
- `model` (string): Restrict to one model slug or alias.
- `api_key_id` (uuid): 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": "claude-opus-5-5", "requests": 9800, "input_tokens": "40012001", "output_tokens": "5010002", "tokens_debited": "26200000", "cost_usd": "52.400000" },
    { "model": "claude-opus-5-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

**`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`**

- `months` (integer, default `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`.

- `limit` (integer, default `50`): Up to 200.
- `before` (string): ISO-8601 timestamp; returns requests created strictly before it.

```json
{
  "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
}
```

- `status` (string): `success`, `error`, `provider_error`, `rate_limited`, `insufficient_balance`, `cancelled` or `blocked`.
- `source` (string): `api`, `chat` (web chat) or `playground`.
- `error_code` (string | 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

**curl**

```bash
# 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"
```

**JavaScript**

```javascript
const url = new URL('https://api.claudech.com/v1/usage/daily');
url.searchParams.set('start', '2026-09-01');
const res = await fetch(url, { headers: { authorization: `Bearer ${process.env.CLAUDECH_API_KEY}` } });
const { data } = await res.json();
for (const d of data) console.log(d.date, d.requests, d.cost_usd);
```

**Python**

```python
import os, requests
r = requests.get(
    "https://api.claudech.com/v1/usage/requests",
    params={"limit": 100},
    headers={"authorization": f"Bearer {os.environ['CLAUDECH_API_KEY']}"},
)
for row in r.json()["data"]:
    print(row["created_at"], row["model"], row["tokens_debited"])
```

---

Source: https://claudech.com/docs/api/usage
