# Credit balance

URL: https://email-validation.org/docs/api/credits/
Updated: 2026-10-20

> Documentation index: https://email-validation.org/llms.txt

`GET /v1/credits` returns the credits you can spend now, any debt, credits that are still being applied, and your
credit lots with their expiry dates. It is free and needs a key with the `account:read` scope.

## Request

**curl**

```bash
curl https://api.email-validation.org/v1/credits -H "Authorization: Bearer $EV_API_KEY"
```

**JavaScript**

```js
const res = await fetch('https://api.email-validation.org/v1/credits', {
  headers: { Authorization: `Bearer ${process.env.EV_API_KEY}` },
});
const credits = await res.json();
if (!res.ok) throw new Error(`${credits.error.code}: ${credits.error.message}`);
console.log(`Balance: ${credits.balance}`);
```

**Python**

```python
import os

import requests

resp = requests.get(
    "https://api.email-validation.org/v1/credits",
    headers={"Authorization": f"Bearer {os.environ['EV_API_KEY']}"},
    timeout=10,
)
resp.raise_for_status()
credits = resp.json()
print("Balance:", credits["balance"])
for lot in credits["lots"]:
    print(lot["remaining"], "credits expire on", lot["expires_at"][:10])
```

## Response

```json
{
  "balance": 24350,
  "debt": 0,
  "pending": 0,
  "lots": [
    {
      "remaining": 850,
      "expires_at": "2027-03-14T12:00:00.000Z"
    },
    {
      "remaining": 23500,
      "expires_at": "2028-09-30T08:15:00.000Z"
    }
  ]
}
```

| Field | Type | Description |
|---|---|---|
| `balance` | integer | Credits you can spend now. |
| `debt` | integer | Credits owed after a refund or reversal; new credits pay this off first. |
| `pending` | integer | Credits granted moments ago that are still being applied. They become spendable shortly. |
| `lots` | array of [CreditLot](https://email-validation.org/docs/api-reference/#schema-creditlot) | Credit lots with credits left, soonest-expiring first. Credits are spent in this order. |

Each lot is one grant of credits (your sign-up credits, a purchase with its bonus, or an adjustment). Lots appear
soonest-expiring first, which is also the order we spend them in, so credits that are about to expire are used
before newer ones.

## Debt and pending credits

- **`debt`** is above 0 only after credits had to be taken back, for example after a payment was reversed. New
  credits pay off debt first.
- **`pending`** counts credits granted a moment ago, for example right after a purchase, that are still being
  applied. They become part of `balance` within seconds.

## Related

- [Credits and billing](https://email-validation.org/docs/credits-and-billing/): what costs a credit, the bonus and expiry rules.
- [Usage](https://email-validation.org/docs/api/usage/): credits used per day or per key.
- [Webhooks](https://email-validation.org/docs/webhooks/): `credits.low` and `credits.expiring` events.