Included usage
Each plan carries a monthly pool of included usage, measured in dollars. Every request draws from that pool according to the model you asked for and the tokens it used — heavier models draw faster, so the same pool goes much further on the workhorse tier than on a flagship. One meter, no per-model gates — every model on a paid plan, the open-model lineup on Free. On models that price cached input, repeated context draws less: it counts at that model’s published cached rate. Where a model publishes no cached rate, repeated context counts at the ordinary input rate — we don’t discount what the model doesn’t — see Prompt caching.
Free is a one-time $2 credit granted when you sign up — it is not renewed each
month. When it runs out, either load credit and
keep going pay-as-you-go at list rates (zero markup), or move to a subscription tier for a
pool that does refresh monthly.
On a subscription tier the pool refreshes at the start of each monthly cycle. As it runs
low, the heaviest models pace to your plan while everything else keeps full speed. The
pool is also a hard cap: once it is used up, requests return
429 allowance_exhausted until the cycle resets — your plan never bills or serves past
the usage it includes. Upgrading lifts it immediately.
Prepaid credit behaves differently, and your client should treat it differently: an empty
balance returns 429 credits_exhausted with no Retry-After, because there is no
reset date to wait for — only a top-up clears it. Branch on the two codes rather than
retrying both.
Track your month in the dashboard under
/dashboard/usage — it shows the same meter
the API enforces.Rate limits
Two published limits per plan: sustained requests per minute and concurrent requests (simultaneous in-flight calls, the axis that matters for parallel agent fleets).Hitting a limit: 429 + retry-after
Past a limit, the API returns429 with a retry-after header — the number of seconds
to wait before retrying. The same status covers both cases:
- Rate limit — you sent requests faster than your plan’s per-minute rate or held too
many open at once.
retry-afteris typically a few seconds. - Monthly cap — an account ceiling for the month was reached.
retry-afterpoints at the next monthly cycle; upgrading clears it immediately.
A rate-limited response
retry-after exactly and add exponential backoff with jitter for repeated hits —
the full recipe is on Errors. Current-window state is also reported on every
response via the x-ratelimit-* headers — see Headers.