Developers
Rate limits
Per-key budgets, the headers that report them, and how to back off.
Limits are per key, as a token bucket: a burst of 60 calls, refilling at one call per second. Every keyed response reports the bucket:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Bucket size for this key. |
X-RateLimit-Remaining | Calls left before a 429. |
X-RateLimit-Reset | Unix time, in seconds, when a call is next allowed. |
Retry-After | On a 429 only: seconds to wait. |
Backing off
Wait the Retry-After seconds, then retry. If you do not read the header, back off exponentially from one second with jitter and stop after five tries. Reads are safe to retry as often as you like; they change nothing.
Good to know
- Budgets are per key, not per workspace. Two tools with two keys do not share a bucket.
- The Insights endpoints are cheap on the ShowPilot side whatever your traffic, so the bucket is the only ceiling. A nightly warehouse pull fits inside it many times over.
- Expensive calls will cost more units when they arrive (a retrieval query, a large expansion); the headers will report units, not requests, and the reference will say what each call costs.