> For the complete documentation index, see [llms.txt](https://docs.claret.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.claret.app/api-guide/credits-and-usage.md).

# API Credits & Usage

Claret meters API usage with **credits**. Each request deducts a fixed number of credits based on the kind of work it does. Credits are allocated monthly per tenant.

## Cost categories

Every endpoint belongs to a cost category. The cost is **flat per request**; it does not scale with the number of rows returned or submitted.

| Category           | Credits / request | Endpoints                                                                       |
| ------------------ | ----------------- | ------------------------------------------------------------------------------- |
| Reference data     | 1                 | `GET` on master data (items, uoms, calendars, locations, customer groups, etc.) |
| Transactional data | 5                 | `GET` on sales, inventory, supply plans, financial plans                        |
| Import             | 10                | File-based import endpoints                                                     |
| Compute            | 50                | Supply plan and forecast generation                                             |
| Free               | 0                 | Job status, token management, credit utilities                                  |

{% hint style="info" %}
A few compute and batch endpoints carry an explicit higher cost that reflects the work they trigger: batch supply plan generation is **200**, forecast generation is **100**, and generate-all forecasts is **500**.
{% endhint %}

## Allocation and rollover

* Each tenant receives a **monthly credit allocation** (the default is generous and sized well above expected usage).
* Unused credits **roll over** month to month, up to a cap of **3× the monthly allocation**. Credits above that cap do not accumulate.
* Allocations refresh automatically each month; there is nothing to renew.

{% hint style="info" %}
Credits are allocated monthly. If a tenant consistently approaches its allocation, contact `help@claret.app` to review the allocation.
{% endhint %}

## Monitoring your balance

Every metered response reports credit usage in two places.

**Response headers:**

| Header                    | Meaning                                                  |
| ------------------------- | -------------------------------------------------------- |
| `X-Api-Credits-Used`      | Credits deducted by this request.                        |
| `X-Api-Credits-Remaining` | Credits left in the tenant's balance after this request. |

**Response envelope** (`meta.credits`):

```json
{
  "message": "Items retrieved.",
  "data": { "items": [] },
  "meta": {
    "credits": { "cost": 1, "remaining": 9998999 }
  },
  "links": {}
}
```

### The Usage dashboard

In the Claret app, **Settings → Workspace Settings → API Access → Usage** (Workspace Admins only) gives a fuller picture. Four cards summarize the account:

* **Credit Balance** — credits available right now.
* **Monthly Allocation** — credits granted each month.
* **Rollover Cap** — the ceiling unused credits can accumulate to.
* **Next Allocation** — days until credits refresh.

![The Usage tab with balance cards, chart, and transaction history](/files/KlB9MLuXnVNeWwUEEQ8k)

Below the cards, a chart plots credits used over time (Daily, Weekly, or Monthly), and a **Transaction History** grid lists each allocation and deduction. Rows that bundle a day's activity are clickable, opening a drill-down that itemizes the individual API calls — amount, endpoint, request ID, and time — behind that line.

![Drilling into the API calls behind a day's credit usage](/files/n1ORziYQYOvRX96hiBa0)

For a request-by-request audit trail (timestamp, token, endpoint, method, status, credits, response time), use the **Query Log** tab.

![The Query Log tab listing every API request](/files/GDm9UwaFrZ5SNCUwdKTV)

## Running out of credits

When a tenant's balance cannot cover a request, the request is rejected with `402 Payment Required` and no work is performed. Wait for the monthly refresh, or contact support to review the allocation.

{% hint style="warning" %}
Free-category endpoints (job status, token management) are never blocked by a low balance, so an integration can always check the status of work it already submitted.
{% endhint %}

## Dry runs

Write, compute, and workflow endpoints accept a `dry_run` flag (or the `X-Dry-Run: true` header). A dry-run request validates the payload without performing the work and **does not consume credits**. Use it to check a payload before committing.

## Related documentation

* [Scopes Reference](/api-guide/scopes.md) — which scope each endpoint type requires.
* [Rate Limiting](/api-guide/rate-limiting.md) — request-rate limits, separate from credits.
* [Error Reference](/api-guide/errors.md) — handling `402` and other statuses.