Skip to main content
Short answers to the questions that come up most. Each links to the page with the full detail. Hit an unfamiliar term along the way? The Glossary defines the vocabulary used across these docs.

​
Getting started

Create one on the API keys page in the dashboard. The full key is shown only once at creation — copy it and store it in your secret manager. See Authentication.
The current API is at https://api.creatoraudit.com/v2. Send your key as a bearer token on every request: Authorization: Bearer YOUR_API_KEY. Keys are scoped to a single organization, so every response only includes that organization’s data.
Call GET /v2/whoami. It echoes the organization_id and api_key_name the token resolves to — a quick way to verify a key and see which org it’s bound to. See Authentication.

​
Data and freshness

A new resource has no metrics until its first refresh completes — its last_scrape_time stays null until then. Poll the resource on a sensible interval and wait for last_scrape_time to become non-null. See Data freshness.
Not real-time. CreatorAudit refreshes on a recurring schedule, so values reflect the most recent collection rather than the live platform. Anchor staleness decisions on last_scrape_time, and note individual videos expose scrape_interval_hours. See Data freshness.
No — there are no webhooks. Consumers poll: re-fetch a resource on an interval and watch last_scrape_time. Don’t busy-wait. See Production best practices.
The public API exposes followers, views, plays, likes, comments, shares, saves, and engagement rate. Saves are returned as the saved_count field — Instagram only (null for TikTok). See Platforms & data coverage.

​
Errors and limits

401 (UNAUTHORIZED) means the API key is missing or invalid. Check that you send the Authorization: Bearer YOUR_API_KEY header and that the key is active. See Errors.
403 covers a few cases: an inactive key or subscription (FORBIDDEN), a key missing a required scope (INSUFFICIENT_SCOPE), or a quota limit (QUOTA_EXCEEDED). Branch on the code field to tell them apart. See Errors.
404 (NOT_FOUND) means the resource doesn’t exist in your organization. Keys are org-scoped, so a valid ID owned by a different organization also returns 404. Re-check the ID and the key. See Errors.
422 (VALIDATION_ERROR) means the request failed validation. The body includes an errors array describing each invalid field — map each back to your input. See Errors.
429 (RATE_LIMITED) means you exceeded the rate limit. Read X-RateLimit-Remaining and X-RateLimit-Reset (and Retry-After when present), then back off exponentially. See Rate limits.
A 403 with code: QUOTA_EXCEEDED means you’ve reached your plan’s account quota — POST /accounts returns it when you try to track more accounts than your plan allows. Remove unused accounts or upgrade, then retry. See Usage & billing.

​
Writing data

Send an Idempotency-Key header on POST /accounts, POST /videos, and POST /creators. Use a unique key per logical write; if a retry repeats the same key, the server returns the original result instead of creating a duplicate. See Production best practices.
Send platform (instagram or tiktok) plus a single identifier — a full post URL, the numeric video ID, or (for Instagram) a bare shortcode. The server resolves and normalizes it for you.
Account videos are discovered automatically from a tracked account’s feed. Individual videos are ones you add yourself by URL, shortcode, or ID, even if you don’t track the posting account. Both carry the same engagement metrics. See Key concepts.

​
Billing and versions

Not every call or tracked resource is billable. The dashboard breaks down billable usage against your plan separately from total activity. See Usage & billing.
v2 is the current, stable version — build new integrations on it. v1 is legacy and deprecated: still available for existing integrations, but receiving no new features. Migrate when you can. See Versioning, and the migration guide for the path-by-path map off v1.

​
Still stuck?

Every response includes an X-Request-ID header (mirrored as request_id in error bodies). Include it when you contact support@creatoraudit.com so support can correlate your call to its server-side event.