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

# Credits API

> GET /v1/credits — read your credit balance and this key's spend without spending any.

# GET /v1/credits

Returns the credit balance of the account that owns the API key, and the
credits spent by the calling key. The call is free: it charges nothing and
places no hold.

```
GET https://api.refuseless.com/v1/credits
Authorization: Bearer abl_...
```

```bash theme={null}
curl https://api.refuseless.com/v1/credits \
  -H "Authorization: Bearer $REFUSELESS_API_KEY"
```

## Response

```json theme={null}
{
  "object": "credits",
  "balance": 42.5,
  "reserved": 1.2,
  "available": 41.3,
  "key_limit": null,
  "key_spent": 3.184211,
  "key_spent_since": null,
  "unit": "usd",
  "updated_at": 1793836800
}
```

| Field | Type | Notes |
| - | - | - |
| `object` | string | Always `credits` |
| `balance` | number | Total credits on the account, including credits held by in-flight requests |
| `reserved` | number | Credits held right now by in-flight requests. Each hold is the worst-case cost of its request; the unused part returns to the balance when the request settles |
| `available` | number | What a new request can reserve: `balance` minus `reserved`, capped by `key_limit` |
| `key_limit` | number \| null | What this key's spend budget, or its workspace's limit, still allows. `null` when the key has no budget |
| `key_spent` | number | Credits billed to **this key** for finished requests, all time or since `since`. Excludes in-flight requests (see `reserved`) and usage covered by a plan allowance or promo credits |
| `key_spent_since` | integer \| null | The `since` you passed, or `null` for all time |
| `unit` | string | Always `usd`. Amounts have up to 6 decimal places |
| `updated_at` | integer | Unix time in seconds when the balance was read. Values are live, not cached |

A `200` is returned even when `available` is `0`, so you can alert and pause
before your next request fails with `402 insufficient_credits`.

> [!NOTE]
>
> `balance` counts paid credits only. Free promo credits and subscription plan
> allowances are not included, so a request can still succeed on a plan or
> promo model while `available` is `0`. A promo model is billed to promo
> credits only: it never spends `balance` or a plan allowance, and returns
> `402` once the account has no promo credits left for it.

## Per-key spend

`balance` is shared by every key on the account. To reconcile one key, read
`key_spent`. Pass `since` (Unix seconds, UTC) to count only requests started
at or after that time:

```bash theme={null}
curl "https://api.refuseless.com/v1/credits?since=1793836800" \
  -H "Authorization: Bearer $REFUSELESS_API_KEY"
```

A request counts once it finishes, against the time it started. Spend from a
deleted key cannot be read, since its key no longer authenticates.

## Avoiding cut-off streams

Every request holds its worst-case cost (prompt plus `max_tokens`) before it
starts. When `available` is below that, the hold shrinks `max_tokens` to fit,
and a stream can end early with an `insufficient_credits` error event. Check
`available` before starting long generations, and top up or lower
`max_tokens` when it runs low.

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | `bad_request` | `since` is not a Unix time in seconds |
| 401 | `invalid_key` | Missing, invalid, revoked, or expired API key |
| 429 | `rate_limit_exceeded` | More than 60 balance reads per minute for this key. Separate from your inference rate limit |
| 503 | `gateway_down` | Billing service unreachable. Retry with backoff |

Errors use the [standard error shape](https://docs.refuseless.com/guides/errors.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.