Documentation menu

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#

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.