> ## Documentation Index > Fetch the complete documentation index at: https://docs.nano-gpt.com/llms.txt > Use this file to discover all available pages before exploring further. # Subscription Usage > Read subscription token quotas and billing-routing advice for your inference API key. ## Choose the right credential For a quota widget or monitoring script, use a [Usage only management token](/api-reference/management-api). 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 ` or `x-api-key: ` ```bash theme={null} curl https://api.nano-gpt.com/api/subscription/v1/usage \ -H "Authorization: Bearer $NANOGPT_API_KEY" ``` ## Response The response includes `active`, `state`, `limits`, `dailyInputTokens`, `weeklyInputTokens`, `dailyImages`, `period`, and `routing`. See the [quota example and field definitions](/api-reference/management-api#read-subscription-usage) 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: | Value | Meaning | | - | - | | `subscription` | This key permits subscription billing and quota is available or temporarily unknown, rather than known to be exhausted | | `paygo` | Subscription use is unavailable or exhausted and the key's policy permits paid-balance spending | | `unavailable` | Neither billing mode is usable under the known subscription and key policy | `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](/api-reference/endpoint/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. ## OpenAPI ````yaml GET /subscription/v1/usage openapi: 3.1.0 info: title: NanoGPT API description: >- API documentation for the NanoGPT language, image, video, speech-to-text, and text-to-speech generation services license: name: MIT version: 1.0.0 servers: - url: https://api.nano-gpt.com/api description: >- Direct API for uploads and long-running requests; choose a model listed by this host - url: https://nano-gpt.com/api description: Website API for current text model examples security: [] paths: /subscription/v1/usage: get: summary: Read subscription usage and routing advice description: >- Requires an inference API key. For monitoring without spending permissions, use a usage:read management token with /api/management/v1/subscription/usage. Input-token quotas count tokens, not requests. operationId: getSubscriptionUsage responses: '200': description: >- Subscription quotas and billing-routing advice. Unavailable counters are null with degraded=true. content: application/json: schema: type: object additionalProperties: true required: - active - state - limits - dailyInputTokens - weeklyInputTokens - dailyImages - period properties: active: type: boolean state: type: string enum: - active - grace - inactive limits: type: object additionalProperties: false required: - dailyInputTokens - weeklyInputTokens - dailyImages properties: dailyInputTokens: type: - number - 'null' weeklyInputTokens: type: - number - 'null' dailyImages: type: - number - 'null' dailyInputTokens: type: - object - 'null' description: >- 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. properties: used: type: - number - 'null' remaining: type: - number - 'null' percentUsed: type: - number - 'null' resetAt: type: - number - 'null' degraded: type: boolean required: - used - remaining - percentUsed - resetAt additionalProperties: false weeklyInputTokens: type: - object - 'null' description: >- 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. properties: used: type: - number - 'null' remaining: type: - number - 'null' percentUsed: type: - number - 'null' resetAt: type: - number - 'null' degraded: type: boolean required: - used - remaining - percentUsed - resetAt additionalProperties: false dailyImages: type: - object - 'null' description: >- 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. properties: used: type: - number - 'null' remaining: type: - number - 'null' percentUsed: type: - number - 'null' resetAt: type: - number - 'null' degraded: type: boolean required: - used - remaining - percentUsed - resetAt additionalProperties: false tokens: type: - object - 'null' description: >- 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. properties: used: type: - number - 'null' remaining: type: - number - 'null' percentUsed: type: - number - 'null' resetAt: type: - number - 'null' degraded: type: boolean required: - used - remaining - percentUsed - resetAt additionalProperties: false period: type: object additionalProperties: false required: - currentPeriodEnd properties: currentPeriodEnd: type: - string - 'null' format: date-time usageUnits: type: string enum: - tokens description: Present for token-based trials. tokenLimits: type: object additionalProperties: false required: - total properties: total: type: number description: Present for token-based trials. routing: type: object description: >- Inference-key-specific billing-policy advice. Does not check current balance, consumed nonzero spend/request caps, or provider health. properties: recommendedMode: type: string enum: - subscription - paygo - unavailable reason: type: string subscriptionQuotaAvailable: type: - boolean - 'null' paidSpendPolicyAllowsBalance: type: boolean '401': description: Missing or invalid inference API key '429': description: Authentication rate limited '500': description: Unable to read usage '503': description: Authentication temporarily unavailable security: - bearerAuth: [] - apiKeyAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer apiKeyAuth: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.