> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octavehq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Credit usage

> Read current credit consumption, remaining credits, additional grants, and reset timing.

Use [Get credit usage](/v2-api-reference/credits/get-credit-usage) to monitor the subscription associated with your API key. The balance is shared across that subscription; it is not limited to requests made by the key or the workspace. The endpoint is unmetered, supports read-only keys, and remains accessible when credits are exhausted.

```bash theme={null}
curl https://app.octavehq.com/api/v2/credits/usage \
  --header "api_key: $OCTAVE_API_KEY"
```

Example response (with `_metadata` omitted):

```json theme={null}
{
  "data": {
    "scope": "subscription",
    "organizationOId": "og_example",
    "subscription": { "oId": "sub_example", "name": "Team plan" },
    "asOf": "2026-09-29T19:00:00.000Z",
    "resetAt": "2026-10-01T00:00:00.000Z",
    "credits": {
      "included": 1000,
      "additional": 500,
      "total": 1500,
      "used": 1200,
      "remaining": 300,
      "additionalUsed": 200,
      "additionalRemaining": 300,
      "exhausted": false
    },
    "overage": null
  }
}
```

## Current usage versus settled credits

Measure settles additional-credit consumption at the end of the billing period. Its stored grant balance can therefore include credits already spent this period. Octave combines the current-period billing snapshot with its real-time usage ledger, including in-flight charges and refunds, to calculate the usable balance.

In the example, 1,000 included credits and 500 additional credits cover 1,200 credits of usage. The remaining balance is **300**, even if the provider still shows a grant balance of 500 before settlement. `additionalUsed` estimates consumption beyond the included allowance; `additionalRemaining` subtracts that consumption once. `additional` is the extra credit balance available to this period, not lifetime grants or a grant-by-grant audit log.

`remaining` is clamped to zero. `resetAt` is the next billing-period reset reported by the provider, or null when unavailable. Additional credits can have their own expiration rules and should not be assumed to reset on that date. `asOf` is the response calculation time; billing updates and charge ingestion can have short propagation delays.

## Overage and unavailable balances

When the plan supports paid overage, `overage` contains its mode, used units, cost in cents, spending ceiling, and whether that ceiling has been reached. `credits.exhausted` means the included and additional credits are used up; paid processing may continue if the overage ceiling allows it. A null `overage` means no overage billing configuration is present.

If billing usage cannot be retrieved, the endpoint returns **503** instead of reporting an artificial zero balance. Retry with backoff. Requests are limited to 30 per minute.