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

# Credits

> Check your remaining Crustdata API credit balance and recurring credit grant with a single free GET request.

Use this endpoint to check your remaining API credit balance and your
recurring credit grant: how many credits you receive each cycle, how often,
and when the next refresh lands. Poll it to
monitor usage and confirm you have enough credits before a large batch of
requests. You can also view credits and usage in your
[dashboard](https://app.crustdata.com/).

<Note>
  This endpoint is **free** — checking your balance does not consume any
  credits. For how credits are charged per endpoint, see [Pricing](/general/pricing).
</Note>

## Endpoint

```
GET https://api.crustdata.com/account/credits
```

It takes no query parameters or request body. Authenticate with your API key
in the `Authorization` header and send the required
`x-api-version: 2025-11-01` header — requests without it return `400`. Rate
limited to 300 requests per minute.

## Example request

<CodeGroup>
  ```bash Request theme={"theme":"vitesse-black"}
  curl --request GET \
    --url https://api.crustdata.com/account/credits \
    --header 'authorization: Bearer YOUR_API_KEY' \
    --header 'x-api-version: 2025-11-01'
  ```

  ```python Python theme={"theme":"vitesse-black"}
  import requests

  resp = requests.get(
      "https://api.crustdata.com/account/credits",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "x-api-version": "2025-11-01",
      },
  )
  print(resp.json()["account"]["credits"])
  ```

  ```json Response theme={"theme":"vitesse-black"}
  {
    "account": {
      "credits": 9406.5,
      "recurring_credits": 10000,
      "recurring_credits_frequency": "monthly",
      "recurring_credits_refresh_date": "2026-08-01T00:00:00+00:00"
    }
  }
  ```
</CodeGroup>

## Response fields

| Field                                    | Type           | Description                                                                                             |
| ---------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------- |
| `account.credits`                        | number         | Remaining API credits on your account — the shared pool all your API keys draw from. May be fractional. |
| `account.recurring_credits`              | number         | Credits granted each billing cycle. `0` if your plan has no recurring grant.                            |
| `account.recurring_credits_frequency`    | string \| null | Grant cadence (for example `monthly`). `null` if no recurring grant.                                    |
| `account.recurring_credits_refresh_date` | string \| null | ISO timestamp of the next grant refresh. `null` if no recurring grant.                                  |
| `account.wallets`                        | array          | Per-wallet breakdown — only present when your account has credit wallets enabled. See below.            |

## Credit wallets

Accounts with credit wallets enabled hold their balance in two wallets, and the
response includes a `wallets` list breaking the balance down:

* **`recurring`** — your plan's cycle grant. Refreshes on `next_refresh_date`
  and is spent first.
* **`topup`** — credits you purchase. They roll over month to month and expire
  on `expires_at`; every new purchase extends the expiry.

```json Response (wallets enabled) theme={"theme":"vitesse-black"}
{
  "account": {
    "credits": 128179.25,
    "recurring_credits": 1000,
    "recurring_credits_frequency": "monthly",
    "recurring_credits_refresh_date": "2026-08-13T00:00:00+00:00",
    "wallets": [
      {
        "type": "recurring",
        "credits": 850.0,
        "next_refresh_date": "2026-08-13T00:00:00+00:00",
        "expires_at": null
      },
      {
        "type": "topup",
        "credits": 127329.25,
        "next_refresh_date": null,
        "expires_at": "2027-07-31T23:59:59Z"
      }
    ]
  }
}
```

| Field                         | Type           | Description                                                              |
| ----------------------------- | -------------- | ------------------------------------------------------------------------ |
| `wallets[].type`              | string         | `recurring` or `topup`.                                                  |
| `wallets[].credits`           | number         | Credits currently attributed to this wallet. May be fractional.          |
| `wallets[].next_refresh_date` | string \| null | Next refresh of the recurring wallet. `null` on the top-up wallet.       |
| `wallets[].expires_at`        | string \| null | When the top-up wallet's credits expire. `null` on the recurring wallet. |

<Note>
  Gate spending decisions on `account.credits` — it is the balance that controls
  API access. `wallets` is informational: during brief settlement windows the
  wallet rows may not sum exactly to `account.credits`. If your account does not
  have credit wallets, the `wallets` key is absent and the response is unchanged.
</Note>

## Errors

| Status | Body                                                                                                   | Cause                                          |
| ------ | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
| `401`  | `{ "message": "Missing API key in request" }`                                                          | No `Authorization` header.                     |
| `401`  | `{ "message": "Invalid API key in request" }`                                                          | `Authorization` header carries an invalid key. |
| `400`  | `{ "error": { "type": "invalid_request", "message": "Missing required header: x-api-version. ..." } }` | No `x-api-version` header.                     |
| `429`  | —                                                                                                      | More than 300 requests per minute.             |

## Per-call usage: the `X-Credits-Used` header

Every response from the data API endpoints — search, enrich, identify,
autocomplete, web, and batch — includes an `X-Credits-Used` header reporting
the exact credits that request deducted:

```bash Request theme={"theme":"vitesse-black"}
curl -i --request POST \
  --url https://api.crustdata.com/person/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{"filters": {"field": "basic_profile.name", "type": "(.)", "value": "Jane"}, "limit": 1}'
```

```http Response headers theme={"theme":"vitesse-black"}
HTTP/2 200
x-credits-used: 0.03
```

The value is an exact decimal (for example `3`, `0.09`). Endpoints that don't
consume credits report `0`, and the header also appears on error responses, so
you can log it on every call.

When reconciling header values against your balance:

* Balance deduction rounds a fractional cost up to the next whole credit, so
  header values summed across requests can be slightly less than your balance
  change.
* Asynchronous work is billed when the job runs, not at submission: batch job
  submissions and background-job searches report `0`.
* Responses generated before a request reaches the API — for example a `429`
  from rate limiting — do not carry the header.

## Auto top-up

Auto top-up automatically buys more credits when your balance runs low, so your
requests keep working instead of failing at zero. You set it up in your
dashboard.

<Note>
  Auto top-up is configured in your [dashboard](https://app.crustdata.com/)
</Note>

### Turn it on

<Steps>
  <Step title="Open the Credits page">
    Go to the **Credits** page in your [dashboard](https://app.crustdata.com/).
  </Step>

  <Step title="Turn on Auto top-up">
    Under **Auto top-up**, click **Turn on**.
  </Step>

  <Step title="Add a card">
    Add a card and authorize automatic charges.
  </Step>

  <Step title="Set your amounts">
    Choose the balance **threshold** that triggers a top-up and the **reload
    amount** to add each time, then click **Save**.
  </Step>
</Steps>

### Settings

* **Threshold:** when your balance falls below this number of credits, a top-up runs.
* **Reload amount:** how many credits to add each time. Set this comfortably above your threshold so one top-up gives you real runway before the next one.
* **Monthly limit** (optional): the most credits Auto top-up can add in a calendar month. Once you reach it, top-ups pause until the next month.
* **Notification emails:** the addresses that receive the Auto top-up notices.

<Note>
  Each top-up is charged to your saved card at your standard credit rate,
  including any volume discount. See [Pricing](/general/pricing) for rates.
  The exact charge is shown before you save.
</Note>

### How you're charged

Each top-up charges your saved card automatically and adds the credits as soon
as the payment succeeds. You get an email receipt, and the invoice appears in
your **Invoices** tab.

### If a payment fails

If a charge is declined, we retry it. If it keeps failing, we turn off Auto
top-up and email you so you can update your card.

### Turn it off or change your card

Turn off Auto top-up any time from the Credits page. Use **Replace card** to
change the card. Removing your card also turns off Auto top-up.

## Per-key monthly limit

Account credits are shared, but a workspace admin can cap how many of them an
individual API key spends each month. Set the cap on the **API Keys** page in
your [dashboard](https://app.crustdata.com/). It applies to that one key and
resets on the 1st of each month (UTC), and your other keys keep drawing on the
account balance as usual.

Use it for a key you hand to a teammate, a customer, or an unattended job, so
one key cannot spend the whole balance. The cap covers the endpoints that
consume credits.

### When the cap is reached

Calls made with that key return `402` until the cap resets or an admin raises it:

```json theme={"theme":"vitesse-black"}
{
  "error": {
    "type": "insufficient_credits",
    "message": "This API key's monthly credit limit has been exhausted. It resets on Aug 01, 2026 (UTC). A workspace admin can raise or disable the limit in the dashboard.",
    "metadata": []
  }
}
```

The status and `error.type` are the same as an account-level out-of-credits
response, so a client that already handles `402` needs no new code. Only the
message differs, which is how you tell the two apart in a log. The reset
sentence appears when a reset date is known.

Raising or removing the cap takes effect on the next call.

### Stopping a key

Set a key's monthly limit to `0` to block it from the next call onward. It stays
blocked until an admin raises the limit — it does not start working again on the
1st of the month.

## What to do next

* **Understand charges** — see [Pricing](/general/pricing) for per-endpoint credit costs.
* **Avoid 429s** — review [Rate limits](/general/rate-limits) when polling at scale.
* **Check API access** — see [Permissions](/general/permissions) for which endpoints and fields your account can use.


## Related topics

- [Pricing](/general/pricing.md)
- [Company Search](/company-docs/search/introduction.md)
- [Search Jobs](/job-docs/search/introduction.md)
- [Person Enrichment](/person-docs/enrichment/introduction.md)
- [Best practices](/openapi-specs/2025-11-01/best-practices.md)