---
title: Usage API
description: Read monthly metered quantities, normalized units, projected amounts, and missing rate-card coverage.
species: reference
---
# Usage API

Usage is read-only, requires `data:read`, and comes from Supernova's hourly usage ledger and rate cards. The endpoint makes no live billing-provider request.

## Read a month

```endpoint
GET /usage
```

Without parameters, returns the current UTC month. Pass `period=YYYY-MM` for another month.

```bash
curl "https://api.supernova.ai/usage?period=2026-07" \
  -H "Authorization: Bearer pat_..."
```

Quantities are converted to their displayed units. Priced lines carry `amount_cents`. An unpriced usage kind has `amount_cents: null` and appears in `missing_rate_card_kinds`; clients must not treat null as zero cost.

| Kind | Display unit |
|---|---|
| `compute_gb_sec` | GB-hour |
| `storage_gb_hour` | GB-month |
| `egress_byte` | GB |
| `read_op`, `write_op`, `list_op` | million operations |
| `ai_token_in`, `ai_token_out` | million tokens |

## List available months

Pass `periods=1` to list months with usage, newest first. `period` and `periods=1` cannot be combined.

`400 invalid_period` reports a malformed month or the invalid combination. `400 invalid_periods` reports a value other than `1`.

Current-month values are projections and can change as new hourly records arrive. Closed-month values remain grounded in the same ledger but can change if a corrected rate card is applied.