> ## Documentation Index
> Fetch the complete documentation index at: https://docs.creatoraudit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ & troubleshooting

> Quick answers to common CreatorAudit API questions — keys, freshness, error codes, duplicates, and versions.

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](/glossary) defines
the vocabulary used across these docs.

## Getting started

<AccordionGroup>
  <Accordion title="How do I get an API key?" icon="key">
    Create one on the [API keys page](https://app.creatoraudit.com/app/api-keys) in the
    dashboard. The full key is shown only once at creation — copy it and store it in
    your secret manager. See [Authentication](/api-reference/authentication).
  </Accordion>

  <Accordion title="What's the base URL, and how do I authenticate?" icon="link">
    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.
  </Accordion>

  <Accordion title="How do I confirm my key works?" icon="circle-check">
    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](/api-reference/authentication).
  </Accordion>
</AccordionGroup>

## Data and freshness

<AccordionGroup>
  <Accordion title="Why does a newly tracked account or video have no metrics yet?" icon="hourglass-start">
    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](/data-freshness).
  </Accordion>

  <Accordion title="How fresh is the data?" icon="clock">
    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](/data-freshness).
  </Accordion>

  <Accordion title="Do you have webhooks?" icon="arrows-rotate">
    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](/best-practices).
  </Accordion>

  <Accordion title="What metrics are available, and where are saves?" icon="chart-simple">
    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](/platforms).
  </Accordion>
</AccordionGroup>

## Errors and limits

<AccordionGroup>
  <Accordion title="What does 401 mean and how do I fix it?" icon="lock">
    `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](/api-reference/errors).
  </Accordion>

  <Accordion title="What does 403 mean?" icon="ban">
    `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](/api-reference/errors).
  </Accordion>

  <Accordion title="What does 404 mean?" icon="magnifying-glass">
    `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](/api-reference/errors).
  </Accordion>

  <Accordion title="What does 422 mean?" icon="triangle-exclamation">
    `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](/api-reference/errors).
  </Accordion>

  <Accordion title="What does 429 mean and how do I handle it?" icon="gauge-high">
    `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](/api-reference/rate-limits).
  </Accordion>

  <Accordion title="What is QUOTA_EXCEEDED?" icon="layer-group">
    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](/dashboard/usage).
  </Accordion>
</AccordionGroup>

## Writing data

<AccordionGroup>
  <Accordion title="How do I avoid creating duplicates?" icon="copy">
    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](/best-practices).
  </Accordion>

  <Accordion title="What can I pass to POST /videos to track a post?" icon="film">
    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.
  </Accordion>

  <Accordion title="What's the difference between account videos and individual videos?" icon="layer-group">
    **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](/concepts).
  </Accordion>
</AccordionGroup>

## Billing and versions

<AccordionGroup>
  <Accordion title="What's the difference between billable and total usage?" icon="receipt">
    Not every call or tracked resource is billable. The dashboard breaks down billable
    usage against your plan separately from total activity. See [Usage &
    billing](/dashboard/usage).
  </Accordion>

  <Accordion title="What's the difference between v1 and v2?" icon="code-branch">
    `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](/api-reference/versioning), and the
    [migration guide](/migration) for the path-by-path map off `v1`.
  </Accordion>
</AccordionGroup>

## 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](mailto:support@creatoraudit.com) so support can correlate
your call to its server-side event.