Developer API
Usage and balances
Read current balances, live usage, reservations, credit wallets, transactions, and entitlements. Balance top-ups and subscriptions are managed in the signed-in web account, not through server-side API keys.
#Read-only usage and balances
Use these endpoints for B2B reconciliation: current balances, settled usage, reservations, credit wallets, transactions, and entitlements. Payment provider checkout and subscription management stay in the signed-in web account.
| Method | Endpoint | Auth | Scope | Audience | Description |
|---|---|---|---|---|---|
| GET | /billing/credits | API key | billing.read | Developers | Return product credit wallets plus ai_gateway_balance_micros. |
| GET | /billing/transactions | API key | billing.read | Developers | List billing transactions with optional product filter. |
| GET | /billing/entitlements | API key | billing.read | Developers | Return active subscriptions and period-end cancellation fields. |
| GET | /ai-gateway/balance | API key | ai.gateway | Developers | Return balance_micros, pending reservation micros, available balance, and USD display values. |
| GET | /ai-gateway/usage | API key | ai.gateway | Developers | List AI Gateway usage events with provider, model, status, date, and limit filters. |
| GET | /ai-gateway/reservations | API key | ai.gateway | Developers | List active, failed, and settled preflight reservations for idempotency and pending-balance debugging. |
/billing/creditsReturn product credit wallets plus ai_gateway_balance_micros.
/billing/transactionsList billing transactions with optional product filter.
/billing/entitlementsReturn active subscriptions and period-end cancellation fields.
/ai-gateway/balanceReturn balance_micros, pending reservation micros, available balance, and USD display values.
/ai-gateway/usageList AI Gateway usage events with provider, model, status, date, and limit filters.
/ai-gateway/reservationsList active, failed, and settled preflight reservations for idempotency and pending-balance debugging.
#Credit fields
Video, Ricochet, and AI Gateway responses expose credit, token, charge, and balance fields so clients can show clear usage state.
credits_deductedremaining_creditsapproval_requiredbudget_exceededinput_tokensoutput_tokensestimated_charge_microscustomer_charge_microsavailable_balance_micros#Idempotency
Only implemented create/hosted-usage flows should send Idempotency-Key: video generation, repurpose, AI Gateway chat, and Ricochet hosted usage.
Idempotency-Key