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

# Credits and billing

> How Finowl counts credits, when a request is charged and how to top up.

Finowl uses one simple unit: **1 credit = 1 lookup**.

| Request | Credits |
| - | - |
| `POST /v1/breaches/email` | 1 |
| `POST /v1/breaches/password` | 1 |
| `POST /v1/gender/name` | 1 |
| `POST /v1/gender/email` | 1 |
| `POST /v1/gender/username` | 1 |
| `POST /v1/gender/batch` | 1 per item (1 to 50) |

The price does not change with the result. An `identified` prediction, an `unknown` prediction, a breached email and a clean email all cost the same.

## Where credits come from

<CardGroup cols={2}>
  <Card title="Monthly free credits" icon="calendar">
    Every account gets **1,000 free credits per calendar month**. They reset at 00:00 UTC on the 1st and do not roll over. Free credits are always used first.
  </Card>

  <Card title="Credit packs" icon="box">
    When the monthly credits run out, Finowl draws from purchased credits. Purchased credits **never expire**. See [pricing](https://finowl.co/pricing).
  </Card>
</CardGroup>

Buy credits from [Billing](https://app.finowl.co/billing) in the dashboard. Credits are shared by every API key on your account.

## When a request is charged

Finowl reserves credits **before** running the lookup, and keeps them whatever the outcome. That means:

| Outcome | Charged? |
| - | - |
| `200` success, including `unknown` predictions and batches with some item errors | Yes |
| `502`, `503` or `504` after the lookup started | Yes |
| `429 provider_rate_limited` | Yes |
| `400`, `401`, `404`, `405`, `413`, `415` (a problem with your request) | No |
| `429 rate_limited` or `429 quota_exceeded` | No |
| `503 provider_not_configured` | No |

The rule of thumb: **if Finowl rejected your request before doing any work, it is free. If the lookup was attempted, it is charged.** This is why validating inputs on your side and [not retrying blindly](/concepts/retries) matter.

## Running out of credits

When your balance cannot cover a request, the API returns:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 60

{ "error": { "code": "quota_exceeded" } }
```

For a batch, every item must be covered. A 50-item batch with 49 credits left is rejected as a whole and costs nothing. Send a smaller batch or top up.

<Tip>
  `quota_exceeded` will not fix itself in 60 seconds unless your monthly credits are about to reset. Alert your team on this code instead of retrying it in a loop.
</Tip>

## Tracking usage

The [dashboard overview](https://app.finowl.co) shows requests, credits used, successes and failures for the current month, broken down by endpoint and by day. The [Logs](https://app.finowl.co/logs) page lists individual requests with their status and duration.


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