Usage (period) — Markdown source

> **AI Agents**: Index `/api/llms.txt` | Full `/api/llms-full-en.txt` | OpenAPI `/api/openapi.yaml`
> Base URL: `<BASE_URL>/v1`

# Usage (period)

Aggregate token usage for the current API key over a time window (**no money amounts**; use balance delta or per-request billing for charges).

```
GET <BASE_URL>/v1/usage?start_time=<unix_sec>&end_time=<unix_sec>
```

## Authentication

Required: `Authorization: Bearer <API_KEY>`.

## Query (required)

| Param | Description |
|-------|-------------|
| `start_time` | Unix **seconds** (inclusive start) |
| `end_time` | Unix **seconds** (exclusive end; must be greater than `start_time`) |

Missing or invalid params return **400**, e.g. `start_time must be a Unix timestamp in seconds`.

## Response (200)

```json
{
  "start_time": 1730700000,
  "end_time": 1730786400,
  "requests": 12,
  "usage": {
    "input_tokens": 1000,
    "cached_write_tokens": 200,
    "cached_write_short_tokens": 150,
    "cached_write_long_tokens": 50,
    "cached_read_tokens": 80,
    "output_tokens": 300,
    "total_tokens": 1580
  }
}
```

| Field | Description |
|-------|-------------|
| `requests` | Request count in the window |
| `usage.input_tokens` | Plain input (excludes cache read) |
| `usage.cached_read_tokens` | Cache read total |
| `usage.cached_write_tokens` | Cache write total |
| `usage.cached_write_short_tokens` / `cached_write_long_tokens` | Short/long TTL write (x6 extension) |
| `usage.output_tokens` / `total_tokens` | Output / total |

Scoped to the **current API key** only.

## Related

- [Billing balance](./billing-balance.md)
- [Billing request](./billing-requests.md)
- [Model pricing](./model-pricing.md)