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

# API credits

> Every Introw plan includes a free monthly allowance of API credits. Learn what spends a credit, how to read your usage, and what happens when the allowance runs out.

Every Introw plan includes API access with a **free monthly allowance** of API credits. There is no add-on to buy and no commercial conversation to have first: create a key and start calling.

One successful API request spends one credit. The allowance resets on the first day of each calendar month, UTC. If your integration needs more room than the free allowance gives it, the allowance can be [raised for your organisation](#increase-your-allowance).

## What spends a credit

A credit is spent when a request reaches an endpoint with a valid API key and the right scope. Nothing else is charged:

| Request                                                                             | Spends a credit            |
| ----------------------------------------------------------------------------------- | -------------------------- |
| An authenticated, correctly scoped request to any `/api/v1` endpoint                | Yes                        |
| A request whose `x-api-key` header is missing, invalid, expired, or revoked (`401`) | No                         |
| A request whose key does not hold the endpoint's scope (`403`)                      | No                         |
| A request rejected by the per-minute rate limit (`429`)                             | No                         |
| A request rejected because your allowance is already spent (`402`)                  | No                         |
| A request that fails with a server error on our side (`5xx`)                        | No, the credit is returned |
| Affiliate conversion tracking sent with a publishable key                           | No                         |
| Model Context Protocol tool calls                                                   | No                         |

Every credit costs the same, whatever the endpoint does and however many records the response contains. Pagination is the exception worth planning for: each page is a separate request, so a large page size spends fewer credits than a small one for the same data.

## Check your usage

There are two places to look, depending on whether you are checking in or writing code against it.

**In Introw.** Go to **Settings > Developers**. The **API Credits** bar at the bottom of the Developers sidebar shows the share of this month's allowance you have consumed; click it for the date your credits reset.

**In your integration.** Every metered response carries your allowance and what is left of it:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
x-introw-credits-limit-month: 100
x-introw-credits-remaining-month: 38
```

`x-introw-credits-remaining-month` counts down as you spend, and already accounts for the request that returned it. Read it to slow down, batch differently, or alert before you run out. A `402` carries the same pair, with `0` remaining.

Both headers are absent when:

* The request was not metered, such as an authentication failure. See [what spends a credit](#what-spends-a-credit).
* Your allowance is unlimited. There is no ceiling to count down from.

## When the allowance runs out

Once the allowance is spent, requests return `402 Payment Required` until your credits reset:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "code": "API_CREDITS_EXHAUSTED",
    "message": "Monthly API credit allowance reached. Credits reset at the start of next month. Contact your Introw account team to increase your allowance."
  }
}
```

The response includes a `Retry-After` header with the number of seconds until the reset, and `x-introw-credits-remaining-month: 0`.

Do not retry a `402`. Unlike a `429`, which clears within a minute, a `402` clears only when the allowance resets or your account team raises it. A retry loop against a spent allowance will never succeed.

## Stay inside the allowance

* **Increase your page size.** `limit=100` on a list endpoint spends one credit where `limit=10` spends ten for the same records.
* **Prefer webhooks and CRM sync over polling.** A job that polls every 15 minutes spends roughly 2,900 credits a month on its own. Introw already writes to your CRM, so read the data there instead of asking the API for it on a timer.
* **Cache what does not change often.** Tier names, form schemas, and partner lists change far less than a polling loop assumes.
* **Do not spend credits on health checks.** A liveness probe against a real endpoint is a real request.
* **Back off on the remainder, not on a `402`.** Read `x-introw-credits-remaining-month` and pause non-urgent work while it is low. A `402` means you have already stopped.

## Increase your allowance

Talk to your Introw account team. Your allowance is set per organisation and does not depend on your plan, so it can be raised to match what your integration actually needs.

## Troubleshooting

| Symptom                              | What to check                                                                                                                                       |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `402 API_CREDITS_EXHAUSTED`          | Your monthly allowance is spent. Check the **API Credits** bar in the Developers sidebar (**Settings > Developers**) and contact your account team. |
| The **API Credits** bar is not shown | Your allowance is unlimited, so there is no percentage to display.                                                                                  |
| The credit headers are missing       | Either the request was not metered (check the table above), or your allowance is unlimited.                                                         |
| Usage climbs faster than expected    | Look for a polling job. Log `x-introw-credits-remaining-month` per caller to find which process is spending them.                                   |
| Usage did not reset                  | The allowance resets on the first day of the month, UTC. Check your own timezone against that boundary.                                             |