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

# Credits

> How Croma credits work: what a live lookup and a dataset request cost, what spends nothing, when the balance resets and what a 402 looks like.

Every organization is on a plan with a monthly balance of **credits**, and
every request spends credits according to what it costs to serve:

| Request                                                                               | Credits |
| ------------------------------------------------------------------------------------- | ------- |
| [Live lookup](/live-lookups): the endpoint queries the source when you call it        | 10      |
| [Dataset request](/datasets): the endpoint answers from a copy Croma keeps up to date | 1       |

Plans start free, with no card. What each plan includes and what it costs is
on the [pricing page](https://usecroma.com/pricing).

## What spends nothing

* A cached answer (`X-Cache: HIT`, or `cache_hit: true` on a batch item),
  though the request still needs enough credits to be accepted.
* A failed request.
* Polling a job's status.

[Batch requests](/batch) spend credits per item: a batch of 10 live lookups
spends 100.

## Your balance on every response

Three headers carry the balance. `X-RateLimit-Limit` is the credits your plan
grants each month, `X-RateLimit-Remaining` is what is left after this request,
and `X-RateLimit-Reset` is when the balance refills:

```http theme={"dark"}
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4990
X-RateLimit-Reset: 2026-10-01T00:00:00.000Z
```

The balance resets on the plan's monthly date. Manage the plan from the
[console](https://platform.usecroma.com/billing). Contracts carry their own
monthly number.

## When the credits are spent

A request your remaining credits cannot cover returns `402` with a
`billing_error` envelope. Upgrade from the console, or wait for the reset in
`X-RateLimit-Reset`:

```json theme={"dark"}
{
  "error": {
    "type": "billing_error",
    "code": "plan_limit_reached",
    "message": "Your plan has no credits left for this period. Upgrade at https://platform.usecroma.com/billing or wait until 2026-10-01T00:00:00.000Z."
  }
}
```

<Card title="Next: Rate limits" icon="gauge" href="/rate-limits">
  The hourly ceilings on a few endpoints, every header and how `429` behaves.
</Card>