Skip to main content
GET
Read subscription usage and routing advice

Choose the right credential

For a quota widget or monitoring script, use a Usage only management token. It can read subscription quotas without permission to run models or spend your balance. This endpoint uses an inference API key and also returns billing-routing advice specific to that key. Management tokens are accepted only at GET /api/management/v1/subscription/usage.

Request

  • Method: GET
  • Path: /api/subscription/v1/usage (alias: /api/v1/subscription/usage)
  • Auth: Authorization: Bearer <api_key> or x-api-key: <api_key>

Response

The response includes active, state, limits, dailyInputTokens, weeklyInputTokens, dailyImages, period, and routing. See the quota example and field definitions for the shared usage fields. The inference-authenticated response also includes subscription metadata and allowOverage. Input-token quotas count tokens, not operation counts or dollars. Image quotas count images. percentUsed is a fraction and may exceed 1. Quota resetAt values are UNIX epoch milliseconds; period.currentPeriodEnd is an ISO timestamp or null. Use returned limits and reset times instead of hardcoding them. A null quota/limit is not configured or applicable. When a lookup is unavailable, counters are null with degraded: true. Display unknown, not a full allowance. Token-based trials also include usageUnits, tokenLimits, and tokens.

Billing-routing advice

Use routing.recommendedMode when choosing between included subscription usage and pay-as-you-go billing: routing.reason explains the recommendation. subscriptionQuotaAvailable is true, false, or null (unknown). The weekly routing calculation includes the service’s small enforcement allowance, so the displayed base quota can be exhausted before the recommendation switches to paid usage. The advice checks billing policy and known subscription quotas. It does not check current cash balance, consumed non-zero request/spend caps, the cost of a particular request, or provider health. The generation endpoint remains authoritative. A configured zero daily request or input-token cap makes the recommendation unavailable. active: true alone does not prove quota remains, and a zero cash balance does not prove included subscription tokens are exhausted. Use Check Balance separately when you need cash balances. Clients can reuse advice briefly, but should refresh it after quota or billing errors. Never force a subscription-only key onto paid billing. Retain the NanoGPT request ID when reporting a transient billing issue.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Response

Subscription quotas and billing-routing advice. Unavailable counters are null with degraded=true.

active
boolean
required
state
enum<string>
required
Available options:
active,
grace,
inactive
limits
object
required
dailyInputTokens
object | null
required

Null when this quota is not configured or applicable. Unavailable counters are null with degraded=true. percentUsed is a fraction and may exceed 1. resetAt is UNIX epoch milliseconds.

weeklyInputTokens
object | null
required

Null when this quota is not configured or applicable. Unavailable counters are null with degraded=true. percentUsed is a fraction and may exceed 1. resetAt is UNIX epoch milliseconds.

dailyImages
object | null
required

Null when this quota is not configured or applicable. Unavailable counters are null with degraded=true. percentUsed is a fraction and may exceed 1. resetAt is UNIX epoch milliseconds.

period
object
required
tokens
object | null

Null when this quota is not configured or applicable. Unavailable counters are null with degraded=true. percentUsed is a fraction and may exceed 1. resetAt is UNIX epoch milliseconds.

usageUnits
enum<string>

Present for token-based trials.

Available options:
tokens
tokenLimits
object

Present for token-based trials.

routing
object

Inference-key-specific billing-policy advice. Does not check current balance, consumed nonzero spend/request caps, or provider health.