Rate Limits

The SurfacedBy API is rate-limited per key. Limits are enforced at two windows: per minute and per calendar month. Exceeding either returns a 429 response.

Quotas by surface

Quotas are per key. If you have multiple keys on an Agency account, each key gets its own per-minute budget; they do not share a pool.

Response headers

Every response includes:

• X-RateLimit-Limit - the per-minute limit for this key.
• X-RateLimit-Remaining - requests left in the current minute window.
• X-RateLimit-Reset - Unix epoch seconds when the current window resets.

On 429 responses you also get:

• Retry-After - seconds to wait before retrying. Honour this value exactly.

429 response shape

The body is a standard problem document (see Errors):

{
  "type": "https://docs.surfacedby.com/v1/api/errors#rate_limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "You have exceeded the per-minute request limit for this API key.",
  "request_id": "req_..."
}

Burst behaviour

The per-minute limit is a fixed window, not a token bucket. When a new minute starts, your budget resets to the full allowance. There is no separate burst allowance on top.

503 rate_limit_unavailable

Rarely, the rate limiter itself is temporarily unavailable. When that happens, the API fails closed with a 503 and a short Retry-After. Treat this the same as a 429 for retry purposes. See Errors.

Designing around the limits

• Batch reads by pulling larger pages (respecting the per-endpoint maximum page size) rather than many single-record requests.
• Cache aggressively on your side. Analytics data updates at most daily in practice, so refetching every minute is wasted budget.
• Use webhooks instead of polling whenever you can.