# Key, plan and balance

> Read what an OpenCheese API key can still spend: GET /v1/key, /v1/plan and /v1/balance with their response fields. Free, and not counted against limits.
>
> Web page: https://opencheese.dev/en/docs/account/ · Every docs page: https://opencheese.dev/llms.txt

Three read-only endpoints report what a key can still spend. They take the same key as every
other request, cost nothing and do not count toward your request limits.

Every answer is wrapped in `data`, and every amount is in credits (USD). `null` means there is
no limit, or a window that has not started yet.

## The key: GET /v1/key

```bash
curl https://api.opencheese.dev/v1/key \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY"
```

```json
{
  "data": {
    "label": "Laptop",
    "limit": 50,
    "limit_usage": 12.5,
    "limit_remaining": 37.5,
    "limit_reset": null,
    "usage": 182.4,
    "created_at": "2026-09-01T10:00:00.000Z",
    "last_used_at": "2026-10-17T09:12:00.000Z"
  }
}
```

- `limit` is the key's spending cap. It limits what the key spends from your balance; plan
  usage never counts toward it and is never blocked by it.
- `limit_usage` is the balance spending counted against the cap since it was last reset on the
  **API keys** page, and `limit_remaining` is what is left. Caps never reset on their own, so
  `limit_reset` is always `null`.
- `usage` is everything the key has ever spent, from your plan and your balance.

## The plan: GET /v1/plan

```bash
curl https://api.opencheese.dev/v1/plan \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY"
```

Without a plan the answer is `{"data": null}`. With one:

```json
{
  "data": {
    "name": "Pro",
    "status": "active",
    "started_at": "2026-10-01T09:00:00.000Z",
    "expires_at": "2026-10-31T09:00:00.000Z",
    "auto_renew": true,
    "windows": {
      "five_hour": { "limit": 5, "usage": 1.2, "remaining": 3.8, "resets_at": "2026-10-17T14:00:00.000Z" },
      "weekly": { "limit": 25, "usage": 9.1, "remaining": 15.9, "resets_at": "2026-10-20T09:00:00.000Z" },
      "monthly": { "limit": 100, "usage": 40, "remaining": 60, "resets_at": "2026-10-31T09:00:00.000Z" }
    },
    "options": {
      "balance_allowed": true,
      "use_balance_on_limit": true,
      "use_balance_for_other_models": false
    }
  }
}
```

- The 5-hour window starts with your first charged request, so its `resets_at` is `null` until
  then. The monthly window renews at `expires_at`.
- `balance_allowed` says whether the plan may draw on your balance at all.
  `use_balance_on_limit` continues on your balance once a window runs out, and
  `use_balance_for_other_models` pays for models outside the plan from your balance. Both are
  switches on the dashboard's **Overview** and report `false` when the plan does not allow
  balance use.

## The balance: GET /v1/balance

```bash
curl https://api.opencheese.dev/v1/balance \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY"
```

It reports your balance and this calendar month's usage (UTC), plan and balance charges
together:

```json
{
  "data": {
    "balance": 12.34,
    "month": "2026-10",
    "monthly_usage": { "tokens": 1234567, "credits": 8.9, "requests": 312 },
    "monthly_limits": { "tokens": null, "credits": null }
  }
}
```

`monthly_limits` are account limits an administrator may set; `null` means none.

## Check before a long job

```bash
curl -s https://api.opencheese.dev/v1/balance \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY" | jq '.data.balance'
```

When the balance runs out, or a plan window does and the plan does not continue on your balance
(`use_balance_on_limit`), requests are refused with `plan_limit_reached`; see
[Errors and rate limits](https://opencheese.dev/en/docs/errors.md).