Concepts

Credits and limits

What a call costs, how the balance moves, and the three limits a deterministic integration must design around: one metered call per account at a time, 60 requests per minute per key, and the server-side deadlines.

Credits

A credit is one thousandth of a US dollar of provider cost, rounded up per call: max(1, ceil(cost_usd × 1000 × plan_multiplier)); free calls cost 0.
Each capability page states its typical credits and cost basis. Variable provider cost cannot be quoted exactly in advance; the response reports what was actually charged.
Every metered response carries charged_credits and balance: { used, cap, period_end }. The balance is the account's usage against its monthly allowance; period_end is null on the Free plan.
Refused calls (credits_exhausted, capability_disabled, rate_limited, validation errors) and failed provider calls charge 0. A cached record detail charges 0.
The last admitted call may exceed the remaining allowance by its own provider cost; the debit clamps at the cap. There is no other overrun.

One call at a time per account

Execute, follow-up and Sharpen pass an admission gate: one metered call per account may run at a time, across all keys, OAuth tokens and API processes. A second concurrent call is answered immediately with 429 rate_limited, retryable: true and a Retry-After: 1 header, before any provider work. It is not charged.

Design consequence: serialise calls per account (a queue or a mutex keyed by account). This "another request is already running" 429 ran nothing and can be repeated after the delay. A rarer variant with the same code, "the request admission has expired", is returned after the provider work ran; see retry rules before repeating a mutating call automatically. An interrupted call releases its slot within five minutes.

Rate limit

60 requests per minute per key (per IP when no recognisable bearer is sent), on every route except the public documents. Headers on every response: x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset; on refusal also retry-after.
The two 429 producers use the same code rate_limited; distinguish them by message and by the presence of the x-ratelimit-* headers on the limiter's response.

Deadlines and sizes

Server-side search deadline 15 s by default; 40 s for the capabilities that state it on their page. Record details 20 s. A hit deadline returns 504 provider_timeout.
A four-minute overall abort protects the metering path; set your HTTP client timeout above the search deadline you rely on.
Request bodies are limited to 256 KB; JSON only.
Sharpen input (task, context, approach and draft together) is capped at 60,000 characters.

Retry rules for each error, including which retries are billed, are on the errors and retries page.