Usage API reference
Credit balance and generation usage.
Credit balance
GET /credits
Auth: API key with scope usage:read, or access token.
Requires usage:read. Remaining credits of the account, per balance. Reading never creates or grants credits.
When to use. Before spending with a live key, to tell your human the balance (a screenshot-set quote shows it too).
Credits. Free: no credits.
Responses
200 The balances.
Schema CreditBalances (application/json).
Headers: X-Request-Id , RateLimit , RateLimit-Policy
{
"balances": {
"starter": 0,
"subscription": 0,
"purchased": 4
},
"total": 4
} 400 INVALID_INPUT. A credential sent in the query string is refused before authentication, without RateLimit headers.
Schema ErrorEnvelope (application/json).
Headers: X-Request-Id , RateLimit , RateLimit-Policy
401 UNAUTHORIZED: missing, malformed, unknown, revoked or expired credential.
Schema ErrorEnvelope (application/json).
Headers: X-Request-Id
403 FORBIDDEN: see details.reason.
Schema ErrorEnvelope (application/json).
Headers: X-Request-Id , RateLimit , RateLimit-Policy
429 RATE_LIMITED: the request rate of the API key (details.scope key) or of the account (user) is exhausted for this window, or too many failed authentication attempts came from this IP (no details.scope and no RateLimit headers). Retry after Retry-After seconds.
Schema ErrorEnvelope (application/json).
Headers: X-Request-Id , RateLimit , RateLimit-Policy , Retry-After
default Error (see ErrorEnvelope and /v1/docs/errors).
Schema ErrorEnvelope (application/json).
Headers: X-Request-Id , RateLimit , RateLimit-Policy
Generation usage
GET /usage
Auth: API key with scope usage:read, or access token.
Requires usage:read. Live generations and the credits they used, for the whole account (every API key and surface) in [from, to), bucketed by UTC day, API key or source. Test-key generations are free and not counted. A range may span at most 366 days.
Credits. Free: no credits.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
from | query | string | Start, inclusive. YYYY-MM-DD means 00:00 UTC that day. Default: 00:00 UTC 29 days before the day of to. |
to | query | string | End, exclusive. YYYY-MM-DD includes that whole UTC day. Default: now. At most 366 days after from. |
groupBy | query | UsageGroupBy | Default: "day" |
Responses
200 The usage report.
Schema UsageReport (application/json).
Headers: X-Request-Id , RateLimit , RateLimit-Policy
{
"from": "2026-10-20T00:00:00.000Z",
"to": "2026-10-21T14:03:12.000Z",
"groupBy": "day",
"data": [
{
"key": "2026-10-20",
"generations": 0,
"succeeded": 0,
"failed": 0,
"refunded": 0,
"pending": 0,
"creditsUsed": 0
},
{
"key": "2026-10-21",
"generations": 3,
"succeeded": 2,
"failed": 0,
"refunded": 1,
"pending": 0,
"creditsUsed": 2
}
],
"totals": {
"generations": 3,
"succeeded": 2,
"failed": 0,
"refunded": 1,
"pending": 0,
"creditsUsed": 2
}
} 400 INVALID_INPUT. A credential sent in the query string is refused before authentication, without RateLimit headers.
Schema ErrorEnvelope (application/json).
Headers: X-Request-Id , RateLimit , RateLimit-Policy
401 UNAUTHORIZED: missing, malformed, unknown, revoked or expired credential.
Schema ErrorEnvelope (application/json).
Headers: X-Request-Id
403 FORBIDDEN: see details.reason.
Schema ErrorEnvelope (application/json).
Headers: X-Request-Id , RateLimit , RateLimit-Policy
429 RATE_LIMITED: the request rate of the API key (details.scope key) or of the account (user) is exhausted for this window, or too many failed authentication attempts came from this IP (no details.scope and no RateLimit headers). Retry after Retry-After seconds.
Schema ErrorEnvelope (application/json).
Headers: X-Request-Id , RateLimit , RateLimit-Policy , Retry-After
default Error (see ErrorEnvelope and /v1/docs/errors).
Schema ErrorEnvelope (application/json).
Headers: X-Request-Id , RateLimit , RateLimit-Policy