> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.defdex.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.defdex.io/_mcp/server.

# Credits and limits

DefDex meters API, CLI, SDK and MCP calls in **credits**. Your plan includes a monthly
allowance; one successful data read uses one credit.

> **Note**
>
> Credit limits aren't switched on yet. Your calls are metered so you can see what you use in
> [Billing](https://app.defdex.io/developer/billing), but nothing is blocked or charged. We'll
> announce limits before they apply.

## What uses credits

| Call                                                                                                                   | Credits                         |
| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| Dataset page, record, entity, relationship or award read (REST)                                                        | 1 per request                   |
| MCP data tool call (`search_records`, `get_record`, `get_entity`, `get_related_records`, `search_awards`, `get_award`) | 1 per call                      |
| CLI and SDK calls                                                                                                      | Same as the REST call they make |
| Dataset catalog (`GET /datasets`, `list_datasets`), usage and credit balance                                           | Free                            |
| Proposed corrections (submit, list and read your own)                                                                  | Free                            |
| Failed requests (4xx, 5xx), rate limits (429) and changed builds (409)                                                 | Free; refunded                  |

## How credits work

* **Plan credits** reset at the start of each billing cycle. Unused plan credits don't roll over.
* **Extra credits** you buy or are granted carry over until used. They're spent after plan credits.
* **When credits run out**, data calls return `402 Payment Required` with the date your plan
  credits reset. Free calls (catalog, balance, corrections) keep working.
* **Pay as you go** (paid plans): when plan credits run out, credits are added in $5 increments
  up to a monthly limit you set in Billing. Set the limit to $0 to stop at your plan's credits.

## Check your balance

Every metered response carries an `X-Credits-Remaining` header. To check without spending a
credit:

```bash
curl https://app.defdex.io/api/v1/credits -H "Authorization: Bearer $DEFDEX_API_KEY"
```

```json
{
  "data": {
    "plan": { "id": "free", "name": "Free", "credits": 1000, "rate_per_minute": 60 },
    "remaining_credits": 812,
    "plan_credits_remaining": 812,
    "extra_credits_remaining": 0,
    "cycle_end": "2026-12-03T06:00:00.000Z",
    "enforced": false
  }
}
```

Agents can call the `get_credit_balance` MCP tool. The [Usage](https://app.defdex.io/developer/usage)
page shows requests by day, endpoint and key.

## Rate limits

All keys on an account share one per-minute limit, currently **60 requests per minute**.
Going over returns `429 Too Many Requests` with a `Retry-After` header; wait that many seconds
and retry. A rate-limited call doesn't use credits.

## Errors

| Status | Meaning                                       | What to do                                                         |
| ------ | --------------------------------------------- | ------------------------------------------------------------------ |
| `402`  | Out of credits this cycle                     | Wait for the reset date in the response, or add credits in Billing |
| `429`  | Per-minute limit reached                      | Wait for `Retry-After`                                             |
| `409`  | A new data build was published mid-pagination | Restart from the first page                                        |

See [Errors and retries](/errors) for every status code.