Billing request — Markdown source

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

# Billing request

Look up token tiers and the sell-price charge for a single chat request (Teamo-style).

```
GET <BASE_URL>/v1/billing/requests/{request_id}
```

## Authentication

Required: `Authorization: Bearer <API_KEY>`. Only requests created by **this key** are visible.

## Path

| Param | Description |
|-------|-------------|
| `request_id` | Response header **`X-Request-Id`** (same value as `X-SNX-Trace-ID`). Do **not** use body ids such as `msg_` / `chatcmpl_` / `resp_` |

Usually available within **1–a few seconds** after the call; **404** if not settled yet (retry).

## Response (200)

```json
{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": 1730700123,
  "model": "claude-haiku-5-5-discount",
  "usage": {
    "input_tokens": 100,
    "cached_write_tokens": 80,
    "cached_write_short_tokens": 80,
    "cached_write_long_tokens": 0,
    "cached_read_tokens": 0,
    "output_tokens": 20,
    "total_tokens": 200
  },
  "amount": {
    "value": "0.001234",
    "currency": "USD"
  }
}
```

| Field | Description |
|-------|-------------|
| `amount.value` | Customer sell charge (`sell_amount`) as a decimal string |
| `usage.*` | Aligned with [Model pricing](./model-pricing.md) four tiers; short/long write are extensions |

TTL bucket detail still comes from Messages `usage.cache_creation`; this API returns write totals plus short/long columns.

## Probe tips

1. `GET /v1/billing/balance` → before  
2. `POST /v1/messages` (or chat / responses) → read `X-Request-Id`  
3. Poll this endpoint → check `amount` and tokens  
4. Optionally re-fetch balance; use [Usage (period)](./usage.md) for window totals

## Related

- [Billing balance](./billing-balance.md)
- [Usage (period)](./usage.md)
- [Response Headers](./response-headers.md)
- [Model pricing](./model-pricing.md)