Limits and plans

Three limits. All three are visible on every response, so none of them has to be discovered by hitting it.

Credits and overage What each call costs, how many credits a month, what happens at the ceiling, and which keys stop rather than bill. Rate limits How many credits a minute, and how to back off in a way that does not waste the allowance you paid for. Archive depth How far back your plan may query — the one that silently changes your results rather than refusing them. Plan comparison Every published tier, side by side.

How they interact

They are checked in order, and each answers a different question:

Limit	Question	Hit it and…
Credits a minute	How fast?	`429 credit_rate_limited`. Transient — wait `retry-after`.
Credits a month	How much this month?	Either overage is billed, or `429 insufficient_credits` for a call the credits left cannot cover.
Archive depth	How far back?	Nothing fails. Your window is narrowed and the response says so.

The third is the one to internalise, because it is the only one that changes your results rather than refusing your request. Fewer articles than you expected is a plan boundary you can read off the response, not coverage you have to guess at.

The headers

Every authenticated response carries all of them.

Header	Meaning
x-credits-charged	Credits this call cost, equal to `credits_charged` in the body. 0 for a preview.
x-credits-limit	Credits included this calendar month. Absent when unlimited.
x-credits-per-minute	Credits per minute allowed by this plan.
x-credits-per-minute-remaining	Credits left in the current minute, after this call.
x-credits-per-minute-reset	Seconds until this minute's credits refill.
x-credits-remaining	Credits left this month.
x-credits-reset	Seconds until the monthly allocation resets.
x-credits-used	Credits used this month, including this call.
x-plan-history-days	How far back this plan may query. Absent means the full archive.

x-credits-charged is what that call cost: 1 for a plain search, more when it made the index do more. Credits and overage lists the costs.

GET /account returns the same figures as a body, and account_status does the same over MCP.

One price, on every surface

A call costs the same credits whichever surface it came in on. A tools/call over MCP is charged exactly what the equivalent REST call is, and both draw on one allocation — there is no separate MCP budget, and no discount for either. estimate=true on any call returns its price without running it.

Some calls are free: /account, account_status, the MCP handshake and any preview. A refusal costs nothing, and a 404 costs the operation's minimum, because the lookup ran.