Rate limits

Requests are rate limited per API key. The API tells you where you stand on every authenticated response — read the headers and back off when you approach the limit. CreatorAudit does not publish specific numeric limits; rely on the headers rather than hard-coding a number.

Rate-limit headers

Every authenticated response includes:

Header	Meaning
`X-RateLimit-Limit`	Your ceiling for the current window.
`X-RateLimit-Remaining`	Requests left in the current window.
`X-RateLimit-Reset`	Unix timestamp (seconds) when the window resets.

The unauthenticated GET /health and GET /meta are not rate limited and omit these headers.

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 12
X-RateLimit-Reset: 1718354400

The values above are illustrative. Read X-RateLimit-Remaining and X-RateLimit-Reset at runtime instead of assuming a fixed limit — limits can change without a new API version.

When you hit the limit

Exceeding the limit returns 429 with code: RATE_LIMITED and a Retry-After header giving the number of seconds to wait:

{
  "type": "urn:creatoraudit:error:rate-limited",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded.",
  "code": "RATE_LIMITED",
  "instance": "/v2/accounts",
  "request_id": "a1b2…"
}

Honor Retry-After when present, then fall back to exponential back-off. Slowing down proactively as X-RateLimit-Remaining approaches zero avoids most 429s.

import time
import httpx


def get_with_backoff(client: httpx.Client, url: str, *, max_attempts: int = 5):
    delay = 1.0
    for attempt in range(max_attempts):
        resp = client.get(url)
        if resp.status_code != 429:
            return resp
        # Prefer the server's hint; otherwise exponential back-off.
        wait = float(resp.headers.get("Retry-After", delay))
        time.sleep(wait)
        delay *= 2
    resp.raise_for_status()
    return resp

The same back-off pattern is a good fit for transient 503 (SERVICE_UNAVAILABLE) responses. See Errors.

Be a good client

Paginate efficiently. Use the largest sensible limit (up to 200) to fetch a page set in fewer calls. See Pagination.
Cache with ETags. GET responses carry a strong ETag and Cache-Control: private, no-cache. Send the value back as If-None-Match; an unchanged representation returns 304 Not Modified with an empty body — a conditional request still counts, but you skip the re-download.
Skip include_total unless needed. It adds a COUNT query per request.
Batch with the metrics endpoints. Instead of polling many resources one at a time, use the batch windowed metrics endpoints — POST /v2/accounts/metrics, POST /v2/videos/metrics, and POST /v2/account-videos/metrics — and the video deltas endpoint to retrieve many records in a single call. See the API reference for these endpoints.
Spread out background jobs. Add jitter and avoid bursts so you do not exhaust a window all at once.

For how rate limits sit alongside pagination caps, account quotas, and other ceilings, see Limits & quotas.

Conventions

Accounts

Videos

Creators

Analytics

Overview

Search

System

Rate-limit headers

When you hit the limit

Be a good client

​Rate-limit headers

​When you hit the limit

​Be a good client

Rate-limit headers

When you hit the limit

Be a good client