Rate limits

The API limits how fast a key, and an organisation as a whole, may call.

Limit	Value	Over it
Per key	60 calls a minute	429 rate_limited
Per organisation	180 calls a minute, over all its keys	429 rate_limited
Per organisation, a day	20,000 calls a UTC day	429 daily_limit_reached

The daily limit is shared by every key of your organisation and restarts at 00:00 UTC. WatchTower15 support can raise it for an organisation; see account limits.

The scan cooldown

Running a scan has a limit of its own, beside the call limits: a domain can be scanned once every 10 minutes for each scan type. A second call inside that time answers 429 rate_limited with Retry-After, the seconds left, and starts nothing. It applies to every key, and a call refused for billing (402) does not start it. See acting on incidents and scans.

Reading the limits

Every answer to a call that found its key carries:

• X-RateLimit-Limit — the limit that applies to the call;
• X-RateLimit-Remaining — what is left of it;
• X-RateLimit-Reset — when it restarts.

A 429 also carries Retry-After, the seconds to wait. Wait that long, then retry; do not retry in a tight loop. A job that walks many rows is best paced at one call a second or slower.

Calls that fail authentication are counted apart (per key and per address) and throttled with the same 429 and Retry-After; a key that does not exist cannot be guessed at speed.

At the edge

WatchTower15’s network edge also limits one address to 600 requests a minute, counted across the console and the API together. The limits above are the ones you plan around; the edge’s is a backstop against abuse. A CI provider that sends many customers’ jobs from one shared address is counted together at the edge, so spread the work out or ask support if you meet it.