Skip to main content
This page consolidates the habits that keep an integration healthy in production. Each section links to the convention page that covers it in full — start here, then go deep where you need to.
Build against https://api.creatoraudit.com/v2 and authenticate every request with an organization-scoped bearer key. See Authentication and Versioning.

Manage keys safely

An API key grants full access to your organization’s data, so treat it like a password.
  • Keep it server-side. Store the key in a secret manager and call the API from your backend. Never commit it, embed it in client-side code, or paste it into logs.
  • Use one key per integration. Separate keys let you disable one without disrupting the others, and GET /v2/whoami tells you which key and organization a token resolves to.
  • Rotate without downtime. Create a new key, deploy it, confirm traffic has moved over, then disable the old one. Don’t delete the old key until you’re sure nothing still uses it — disabled keys return 403.

Paginate with cursors, not offsets

List endpoints use opaque cursor pagination. Loop while pagination.has_next is true, passing the previous next_cursor each time, and keep your filters and sort identical across pages — a cursor is bound to the filter and sort it was issued for. Use the largest sensible limit (up to 200) to fetch a page set in fewer calls.
Skip include_total=true unless you actually display the total — it runs an extra COUNT query per request. See Pagination.

Handle rate limits and back off on 429

Every authenticated response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Read them at runtime rather than hard-coding a number, and slow down as X-RateLimit-Remaining approaches zero. On a 429, honor Retry-After when present, then fall back to exponential back-off. The same pattern fits transient 503 (SERVICE_UNAVAILABLE) responses.
See Rate limits for the full header reference.

Cache with conditional requests

GET responses carry a strong ETag. Send the value back as If-None-Match; an unchanged representation returns 304 Not Modified with an empty body, so you skip the re-download and save bandwidth.

Make writes idempotent

POST /accounts, POST /videos, and POST /creators accept an Idempotency-Key header. Send a unique key per logical operation so a retry after a network blip doesn’t create a duplicate — the server returns the original result instead.
Reuse the same key only for retries of the same request. A fresh logical write needs a fresh key.

Poll on a sensible cadence

CreatorAudit refreshes data on a schedule, not in real time, and there are no webhooks — consumers poll. After a write, a new resource’s last_scrape_time is null until its first refresh lands. Re-fetch on an interval (seconds to minutes, not a tight loop) and anchor staleness decisions on last_scrape_time rather than assuming “now”.
Don’t busy-wait. A new account or video needs time to complete its first refresh — see Data freshness for what to expect and how the cadence is set.

Reduce calls with batch metrics

Instead of fetching windowed metrics one resource at a time, request many IDs in a single call with the batch endpoints. Each takes a period (7d, 30d, 90d, or custom with start_date/end_date) and a list of IDs.
Fewer round-trips means fewer rate-limit windows consumed. See Pagination for collection reads and Platforms & data coverage for what each metric means.

Log the request ID on every failure

Every response includes an X-Request-ID header, mirrored as request_id in the RFC 9457 error body. Log it with each failure so support can correlate a call to its server-side event. Branch on the HTTP status for coarse flow and on the code field for specifics.
See Errors for the full status and code reference.

Next steps

API setup

Get a key and make your first authenticated call.

Python example

A worked end-to-end client you can adapt.

For AI agents

Patterns for driving the API from an agent.

Errors

Status codes, code values, and robust handling.