---
title: Usage
---

# Usage

Read your spend, token, and request counts across the current day, week, and
month. Read-only and suitable for polling.

## Endpoint

```http
GET https://api.crossmodel.ai/v1/usage
Authorization: Bearer cm-YOUR_KEY
# Or: x-api-key: cm-YOUR_KEY
```

Accepts either OpenAI-style `Authorization: Bearer` or Anthropic-style
`x-api-key` authentication.

## Get usage

`GET /v1/usage`

```bash
curl https://api.crossmodel.ai/v1/usage \
  -H "Authorization: Bearer cm-YOUR_KEY"
```

Anthropic-style authentication works on the same URL:

```bash
curl https://api.crossmodel.ai/v1/usage \
  -H "x-api-key: cm-YOUR_KEY"
```

```json
{
  "currency": "USD",
  "daily": {
    "cost_micro": 152340,
    "prompt_tokens": 18230,
    "completion_tokens": 4120,
    "total_tokens": 22350,
    "request_count": 12,
    "success_count": 12
  },
  "weekly": {
    "cost_micro": 982110,
    "prompt_tokens": 120400,
    "completion_tokens": 28900,
    "total_tokens": 149300,
    "request_count": 86,
    "success_count": 84
  },
  "monthly": {
    "cost_micro": 3450980,
    "prompt_tokens": 410200,
    "completion_tokens": 96500,
    "total_tokens": 506700,
    "request_count": 312,
    "success_count": 305
  }
}
```

## The usage object

| Field | Type | Notes |
|------|------|------|
| `currency` | string | Currency of all `cost_micro` fields, e.g. `USD`. |
| `daily` | object | Usage window for the current UTC day (since 00:00 UTC). |
| `weekly` | object | Usage window for the current ISO week (since Monday 00:00 UTC). |
| `monthly` | object | Usage window for the current calendar month (since the 1st, 00:00 UTC). |

Each window object has the same shape. `cost_micro` is in **micro units** of
`currency` (1 USD = 1,000,000 micro); divide by 1,000,000 for the decimal amount.

| Field | Type | Notes |
|------|------|------|
| `cost_micro` | integer | Total spend in the window, in micro units. |
| `prompt_tokens` | integer | Sum of input tokens. |
| `completion_tokens` | integer | Sum of output tokens. |
| `total_tokens` | integer | Sum of total tokens. |
| `request_count` | integer | Total requests (all statuses). |
| `success_count` | integer | Requests that completed successfully. |

<Callout type="info">
  Windows use UTC calendar boundaries. Values are cached briefly (about 60
  seconds), so very recent requests may take up to a minute to appear.
</Callout>

## Errors

Bearer-authenticated requests use the OpenAI-compatible error format; requests
carrying a non-empty `x-api-key` use the Anthropic-compatible error format (see
[Models](/docs/api-reference/models#errors) for both shapes).

| HTTP status | `type` | Common `code` | Notes |
|------------|--------|-------------|------|
| `401` | `authentication_error` | `missing_api_key`, `invalid_api_key` | API key missing or invalid. |
| `500` | `api_error` | `db_error` | A CrossModel internal error. |