Skip to main content
Rate limits cap how many requests a client can send in a minute. They keep one client from saturating the API so other traffic still lands. Heartbeat ingest and public status-page reads skip the shared IP budget so they keep working when another client is over quota. Heartbeats still have a route limit (120 / min). You hit a cap when a script, MCP agent, or scanner loops too fast, not when Tallwatch is checking your monitors. Writes are tighter than reads because they change data. Over a cap: 429 with Retry-After, a Link to this page, and:
RateLimit-Limit is the sustained quota for the window. RateLimit-Remaining is burst tokens left, so a short spike can succeed before the sustained cap binds. RateLimit-Reset is 0 while you are under quota. After a 429, RateLimit-Reset and Retry-After are the seconds to wait. Counters are per api process.

What is limited

Identity is either the API key or the client IP. A Bearer key has its own read and write budgets. Every request that is not exempt (below) also counts against the client IP budget. MCP uses the public REST API with your , so it shares the key budgets. list_* / get_* are reads. Create, pause, ack, resolve, and test-check are writes. An agent that calls get_monitor in a loop spends the same 300 reads / min as curl. A Bearer request counts against its key bucket and the client IP bucket. Session-cookie app traffic uses the IP bucket only. Unmatched paths (including wrong-method scans) count against the IP bucket.

Abuse-only routes

Tighter limits on expensive or guessable endpoints. Test-check, password unlock, subscribe, contact, and auth are the usual brute-force or cost targets.

Exempt from the global IP budget

These skip the shared 600 / min IP bucket so ingest and public pages keep working when another client is over quota. Heartbeat ingest still uses the 120 / min route limit above.
  • Heartbeat ingest GET|POST /api/v1/heartbeats/:token
  • Prober /api/v1/jobs and /api/v1/results
  • Sign-in / sign-up (/api/auth/*), which has its own limits above
  • Public status-page reads (page, RSS, badge, by-host, GET verify) and POST /api/v1/public/status-pages/unsubscribe
  • Stripe webhooks, Slack acknowledge, Caddy TLS ask, GET /health, GET /

Handling 429

Wait Retry-After seconds (same value as retry_after_sec), then retry. Do not tight-loop: retries that ignore the header spend the burst bucket again and stay at 429. docs_url is always this page. For MCP, prefer one list_monitors over many get_monitor calls in the same turn. Create and scope keys on . Agent setup is on .