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

# Credit balance

> Check your organization's current credit balance before firing credit-consuming requests.

The Credit Balance API returns your organization's current credit balance as a single, read-only `GET`. Use it to check how many credits you have left before submitting uploads or contacts — for example, to top up ahead of a large batch, or to surface remaining credits in your own dashboard.

It's available to every account with an API key — no special access or [scope](/authentication) needed, and it never costs a credit.

## The balance object

| Field          | Type    | Notes                                                                                                           |
| -------------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `total`        | integer | Total credits available — `subscription + purchased`. This is the number that gates credit-consuming endpoints. |
| `subscription` | integer | Credits from your monthly subscription allocation. Replenished each billing period and capped.                  |
| `purchased`    | integer | Credits from one-time top-up purchases. Uncapped and never expire while your account is active.                 |

Credits are consumed from the `subscription` pool first, then `purchased`.

***

## Retrieve credit balance

```http theme={null}
GET /api/v1/credits/balance
```

Returns your organization's current balance. The organization is resolved from your API key, so there are no parameters.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl "https://api.optimaldial.com/api/v1/credits/balance" \
      -H "Authorization: Bearer $OPTIMALDIAL_API_KEY"
    ```
  </Tab>

  <Tab title="Node.js">
    ```ts theme={null}
    const res = await fetch("https://api.optimaldial.com/api/v1/credits/balance", {
      headers: {
        Authorization: `Bearer ${process.env.OPTIMALDIAL_API_KEY}`,
      },
    });
    const balance = await res.json();
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    resp = requests.get(
        "https://api.optimaldial.com/api/v1/credits/balance",
        headers={"Authorization": f"Bearer {os.environ['OPTIMALDIAL_API_KEY']}"},
    )
    balance = resp.json()
    ```
  </Tab>
</Tabs>

### Response

`200 OK`:

```json theme={null}
{
  "total": 1500,
  "subscription": 1000,
  "purchased": 500
}
```

### Errors

| Status | When                                 |
| ------ | ------------------------------------ |
| `401`  | Missing, invalid, or revoked API key |
| `429`  | Rate limit hit                       |