> ## 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

## Overview

Returns subscription status and current daily/monthly usage for the active billing period.

## Request

* Method: `GET`
* Path: `/api/subscription/v1/usage`
* Auth: `Authorization: Bearer <api_key>` or `x-api-key: <api_key>`

## Response

`200 application/json`. Timestamps are UNIX epoch milliseconds.

```json theme={null}
{
  "active": true,
  "limits": { "daily": 5000, "monthly": 60000 },
  "enforceDailyLimit": true,
  "daily": {
    "used": 5,
    "remaining": 4995,
    "percentUsed": 0.001,
    "resetAt": 1738540800000
  },
  "monthly": {
    "used": 45,
    "remaining": 59955,
    "percentUsed": 0.00075,
    "resetAt": 1739404800000
  },
  "period": {
    "currentPeriodEnd": "2025-02-13T23:59:59.000Z"
  },
  "state": "active",
  "graceUntil": null
}
```

Fields

* `active` — Whether the account is currently active for subscription usage.
* `limits.daily`, `limits.monthly` — Configured daily/monthly allowance.
* `enforceDailyLimit` — Always `true` for subscriptions. Daily and monthly limits are both enforced and the daily limit cannot be disabled.
* `daily.used`, `monthly.used` — Usage units consumed in the current day/month window.
* `daily.remaining`, `monthly.remaining` — Remaining allowance for each window.
* `daily.percentUsed`, `monthly.percentUsed` — Decimal fraction in \[0,1].
* `daily.resetAt`, `monthly.resetAt` — Millisecond epoch when the window resets.
* `period.currentPeriodEnd` — ISO timestamp for the end of the current billing period, if known.
* `state` — One of `active`, `grace`, `inactive`.
* `graceUntil` — ISO timestamp when grace access ends (if applicable).

## Usage semantics

* Usage units represent successful subscription‑covered operations (e.g., a completed generation). They are not tokens or dollar cost.
* Daily window resets at the next UTC day start; monthly usage aligns to the subscription billing cycle when available. Daily limits are always enforced.

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -s \
    -H "Authorization: Bearer $NANOGPT_API_KEY" \
    https://nano-gpt.com/api/subscription/v1/usage | jq
  ```

  ```ts JavaScript/TypeScript theme={null}
  const res = await fetch('https://nano-gpt.com/api/subscription/v1/usage', {
    headers: { 'Authorization': `Bearer ${NANOGPT_API_KEY}` },
  });
  const data = await res.json();
  ```
</CodeGroup>