> ## 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.

# Agent recipes

> End-to-end agent workflows built only from real CreatorAudit endpoints — onboard, report, find, track, and backfill.

These recipes chain real `v2` endpoints into the kind of task an agent runs end to end. Each is idempotency-minded, paginated where it needs to be, and error-aware. Every request needs `Authorization: Bearer YOUR_API_KEY`; the header is omitted below for brevity.

<Note>
  Response fields vary by endpoint — fetch and read the live shape rather than assuming
  it. The interactive [explorer](https://api.creatoraudit.com/v2/docs) shows each
  response in full.
</Note>

## Onboard and report

Start tracking an account, then summarize its recent engagement.

<Steps>
  <Step title="Track the account">
    `POST /v2/accounts` with the platform and handle. Send an `Idempotency-Key` so a retry doesn't create a duplicate.

    ```bash theme={null}
    curl -X POST "https://api.creatoraudit.com/v2/accounts" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: onboard-creator-handle-2026-06-14" \
      -d '{ "platform": "instagram", "username": "creator_handle" }'
    ```

    Read the `id` from the created account in the response.
  </Step>

  <Step title="Pull the last 7 days of analytics">
    `GET /v2/accounts/{id}/analytics` with a date window. Metrics build up over the following scrape cycles, so a brand-new account may have little history yet.

    ```bash theme={null}
    curl "https://api.creatoraudit.com/v2/accounts/{id}/analytics?start_date=2026-06-07&end_date=2026-06-14" \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```
  </Step>

  <Step title="Summarize">
    Feed the returned daily series to the model and ask for a short engagement summary. Quote the `X-Request-ID` from the analytics call in your run log for traceability.
  </Step>
</Steps>

## Daily standup digest

Compose a morning digest from the headline view plus the leaderboard.

<Steps>
  <Step title="Fetch the overview">
    `GET /v2/overview` returns organization-level figures. Pass a `period` (for example `7d`) if you want a windowed view.

    ```bash theme={null}
    curl "https://api.creatoraudit.com/v2/overview?period=7d" \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```
  </Step>

  <Step title="Fetch top creators">
    `GET /v2/creators/top` ranks your creators over a period.

    ```bash theme={null}
    curl "https://api.creatoraudit.com/v2/creators/top?period=7d&limit=5" \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```
  </Step>

  <Step title="Format the digest">
    Hand both JSON payloads to the model and ask for a short standup message — headline numbers from the overview, then the top creators. Post it to Slack, email, or wherever the team reads it.
  </Step>
</Steps>

## Find and track

Discover an account or video by query, then start tracking it.

<Steps>
  <Step title="Search">
    `GET /v2/search?q=...` searches accounts, creators, and videos.

    ```bash theme={null}
    curl "https://api.creatoraudit.com/v2/search?q=cooking&limit=10" \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    Let the model pick the best match from the results and read its identifier.
  </Step>

  <Step title="Track the video">
    `POST /v2/videos` accepts a full post URL (or platform identifier). Use an `Idempotency-Key` keyed to the URL.

    ```bash theme={null}
    curl -X POST "https://api.creatoraudit.com/v2/videos" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: track-https-instagram-com-p-XXXX" \
      -d '{ "platform": "instagram", "identifier": "https://www.instagram.com/p/XXXX/" }'
    ```
  </Step>
</Steps>

<Tip>
  To track a whole account instead of a single post, `POST /v2/accounts` (see the first
  recipe). CreatorAudit then discovers that account's videos for you under
  `/v2/account-videos`.
</Tip>

## Backfill metrics across a video library

Page through every tracked video, then pull windowed metrics for the batch.

<Steps>
  <Step title="Paginate the video list">
    `GET /v2/videos` returns a page of videos plus a `pagination` object. Loop on the cursor until `has_next` is `false`, collecting each video `id`.

    ```bash theme={null}
    # First page
    curl "https://api.creatoraudit.com/v2/videos?limit=200" \
      -H "Authorization: Bearer YOUR_API_KEY"

    # Next page — pass the previous pagination.next_cursor
    curl "https://api.creatoraudit.com/v2/videos?limit=200&cursor=NEXT_CURSOR" \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```
  </Step>

  <Step title="Request metrics in batches">
    `POST /v2/videos/metrics` takes up to 200 video IDs and a window. Send the IDs you collected in batches of 200 with a `period` (`7d`, `30d`, `90d`, or `custom` with `start_date`/`end_date`).

    ```bash theme={null}
    curl -X POST "https://api.creatoraudit.com/v2/videos/metrics" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "video_ids": ["…", "…"], "period": "30d" }'
    ```
  </Step>

  <Step title="Aggregate">
    Merge the metric batches and let the model summarize trends. The same pattern works for accounts via `POST /v2/accounts/metrics` (with `account_ids`).
  </Step>
</Steps>

## Loop discipline for every recipe

<Warning>
  Build these as resilient loops, not one-shot scripts — an agent will retry, and the
  API may return partial pages.
</Warning>

* **Idempotency.** Set an `Idempotency-Key` header on `POST /v2/accounts`, `POST /v2/videos`, and `POST /v2/creators`, keyed to the logical action, so retries don't duplicate.
* **Pagination.** Always read `pagination.has_next` and pass `pagination.next_cursor` as `cursor`. Never assume one page is the whole set.
* **Error awareness.** On `4xx`/`5xx`, parse the RFC 9457 body — branch on `status` and the machine-readable `code` — and back off rather than hammering. Capture `X-Request-ID` from every response.
* **Batch limits.** Metrics endpoints accept 1–200 IDs per call; chunk larger sets.

See [Use the API as agent tools](/agents/tool-use) for the executor that wraps these calls, and the [API reference](/api-reference/introduction) for the shared conventions.