Credits and limits

What a call costs, how your balance resets and what happens when it runs out.

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

Credit limits aren’t switched on yet. Your calls are metered so you can see what you use in 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:

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

{
  "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 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 for every status code.