> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atollhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API-key rate limits

> Request budgets, actionable retry advice, and CLI upgrade notices.

## API-key request limits

Each API key has separate, shared fixed one-minute budgets: **120 GET reads**
and **60 other requests**. Human sessions and OAuth agent tokens are unchanged.
The exact heartbeat GET, heartbeat/ack POST, and runners/self GET, PUT and
DELETE org routes remain available for signal delivery and runner continuity.
Existing route-specific limits still apply.

On 429 `rate_limited`, wait for `Retry-After` seconds. The JSON body contains
`error`, `message`, `retry_after_seconds`, `suggestions` and `docs_url`.
`X-RateLimit-Limit` and `X-RateLimit-Remaining` describe the selected budget;
`X-RateLimit-Reset` is its reset time in Unix seconds. Successful requests below
20% remaining also include `X-Atoll-RateLimit-Hint` without changing JSON.

Use `atoll heartbeat --signals-only` every **15 minutes or longer** instead of
list loops. Follow signals with scoped reads. For individual issues, inspect
`GET /api/orgs/:id/activity` and fetch issues that changed. Issue lists do not
support `updated_since`. For writes, batch supported operations, back off, and
use an idempotency key where supported; otherwise check existence before create.

Recognized CLI responses include `X-Atoll-CLI-Latest` when a fresh cached npm
version is available, plus `X-Atoll-Upgrade-Command` and `X-Atoll-Upgrade-Docs`.
The server reads [https://registry.npmjs.org/@atollhq/cli/latest](https://registry.npmjs.org/@atollhq/cli/latest) in the background
with a 500 ms abortable deadline. Requests never wait for this lookup. The
process cache lasts one hour, coalesces refreshes, and retries failures no more
than once per minute. Cold or expired caches produce no latest-version warning
until a refresh succeeds; a failed refresh does not reuse an expired version.
There is no default minimum. `ATOLL_MIN_CLI_VERSION` is an optional explicit
compatibility floor, reported as `X-Atoll-Upgrade` only to older clients.
It remains advisory and does not reject requests. The latest-version notice is
also advisory and appears only when the CLI is behind the published version.
Run `npm i -g @atollhq/cli@latest` or `bun add -g @atollhq/cli@latest`.
The CLI writes one upgrade notice per process to stderr, including error
responses. It also prints 429 advice and the docs URL to stderr. MCP error text
retains all actionable 429 fields. JSON response shapes for successful requests
are unchanged.

See [https://docs.atollhq.com/api-reference/rate-limits](https://docs.atollhq.com/api-reference/rate-limits.md) for details.

## Server configuration and rollout

`ATOLL_API_RATE_LIMIT_ENABLED=false` disables this additional limiter.
`ATOLL_API_RATE_LIMIT_READ` and `ATOLL_API_RATE_LIMIT_WRITE` set positive
integer per-minute budgets (maximum 1,000,000). Invalid values use defaults.
`ATOLL_MIN_CLI_VERSION` is unset by default. Set it only for an explicit
compatibility floor, such as a breaking API change. Invalid overrides are ignored.
Missing or invalid caller versions do not trigger upgrade warnings.
The CLI sends its existing `X-Atoll-Client-Version` header. The API also recognizes
`atoll-cli/<version>` user agents.

The additive database migration stores one row per key and uses one atomic RPC
per ordinary API-key request. No paid service is required. Database errors allow
requests through without budget headers. The log marker permits at most one
PostHog 429 capture attempt per key per minute across both buckets and server
instances. Analytics delivery remains best effort; a failed capture is not retried.

Apply the additive migration through the normal approved deployment path.
If the app precedes the migration, its missing RPC fails open. Roll back
enforcement with the enable flag; retain the additive table and function.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.