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

# cURL

> Call the CreatorAudit API from the command line with curl and jq.

Every endpoint is a plain HTTPS request, so `curl` is the fastest way to try the
API. The examples below use `curl` for requests and [`jq`](https://jqlang.github.io/jq/)
to parse JSON. Pair them to script anything from a one-off check to a full
paginated export.

<Info>
  Create a key on the [API keys page](https://app.creatoraudit.com/app/api-keys), then
  send it as `Authorization: Bearer YOUR_API_KEY`. Never paste a key into a shared shell
  history — export it as an environment variable instead.
</Info>

## Setup

Export your key once per shell session and reuse it across every call.

```bash theme={null}
export CREATORAUDIT_API_KEY="YOUR_API_KEY"
export CREATORAUDIT_BASE_URL="https://api.creatoraudit.com/v2"
```

<Steps>
  <Step title="Verify your key">
    `GET /whoami` echoes back the organization your key belongs to. Use it to
    confirm the key is valid before scripting anything heavier.

    ```bash theme={null}
    curl --silent --show-error \
      --header "Authorization: Bearer $CREATORAUDIT_API_KEY" \
      "$CREATORAUDIT_BASE_URL/whoami" | jq
    ```

    ```json Response theme={null}
    {
      "data": {
        "type": "whoami",
        "organization_id": "org_2a...",
        "api_key_name": "ci-export"
      }
    }
    ```
  </Step>

  <Step title="List tracked accounts">
    `GET /accounts` returns a page of the accounts your organization tracks.
    Control page size with `limit` (1–200).

    ```bash theme={null}
    curl --silent --show-error \
      --header "Authorization: Bearer $CREATORAUDIT_API_KEY" \
      "$CREATORAUDIT_BASE_URL/accounts?limit=25" | jq
    ```

    The response is the standard cursor envelope. See
    [Pagination](/api-reference/pagination) for the full contract.

    ```json Response theme={null}
    {
      "data": [{ "id": "...", "platform": "tiktok", "username": "creatoraudit" }],
      "pagination": { "next_cursor": "eyJ2IjoxfQ", "has_next": true, "limit": 25 }
    }
    ```
  </Step>

  <Step title="Track an account">
    `POST /accounts` starts tracking a new account. The body requires `platform`
    (`instagram` or `tiktok`) and `username`.

    ```bash theme={null}
    curl --silent --show-error \
      --request POST \
      --header "Authorization: Bearer $CREATORAUDIT_API_KEY" \
      --header "Content-Type: application/json" \
      --data '{
        "platform": "tiktok",
        "username": "creatoraudit",
        "category": "tech",
        "scrape_interval_hours": 24
      }' \
      "$CREATORAUDIT_BASE_URL/accounts" | jq '.data.id'
    ```
  </Step>
</Steps>

## More requests

<CodeGroup>
  ```bash Overview theme={null}
  # period accepts 7d | 30d | 90d
  curl --silent --show-error \
    --header "Authorization: Bearer $CREATORAUDIT_API_KEY" \
    "$CREATORAUDIT_BASE_URL/overview?period=30d" | jq '.data'
  ```

  ```bash Search theme={null}
  # q is matched against usernames, creator names, and video captions
  curl --silent --show-error \
    --header "Authorization: Bearer $CREATORAUDIT_API_KEY" \
    --get --data-urlencode "q=creator" \
    "$CREATORAUDIT_BASE_URL/search" | jq
  ```

  ```bash Track a video theme={null}
  # the body field is "identifier" (a URL, id, or IG shortcode), not "url"
  curl --silent --show-error \
    --request POST \
    --header "Authorization: Bearer $CREATORAUDIT_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "platform": "tiktok",
      "identifier": "https://www.tiktok.com/@creatoraudit/video/712345",
      "is_active": true
    }' \
    "$CREATORAUDIT_BASE_URL/videos" | jq '.data.id'
  ```
</CodeGroup>

## Reading `X-Request-ID`

Every response carries an `X-Request-ID` header. Capture it whenever you need to
share a request with support. Use `--dump-header` to keep the headers while
still piping the body to `jq`.

```bash theme={null}
curl --silent --show-error \
  --dump-header /tmp/ca-headers \
  --header "Authorization: Bearer $CREATORAUDIT_API_KEY" \
  "$CREATORAUDIT_BASE_URL/whoami" | jq '.data'

grep --ignore-case "x-request-id" /tmp/ca-headers
```

## Handling errors

Errors use [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem documents
served as `application/problem+json`. They always include `type`, `title`,
`status`, `detail`, and a machine-readable `code`. Branch on the HTTP status with
`--write-out` and surface the `code` plus the request id on failure.

```bash theme={null}
http_status=$(curl --silent --show-error \
  --output /tmp/ca-body.json \
  --dump-header /tmp/ca-headers \
  --write-out "%{http_code}" \
  --header "Authorization: Bearer $CREATORAUDIT_API_KEY" \
  "$CREATORAUDIT_BASE_URL/accounts?limit=25")

if [ "$http_status" -ge 400 ]; then
  request_id=$(grep --ignore-case "x-request-id" /tmp/ca-headers | tr -d '\r' | awk '{print $2}')
  echo "Request failed ($http_status, request-id: $request_id)" >&2
  jq '{ code, title, detail }' /tmp/ca-body.json >&2
  exit 1
fi

jq '.data' /tmp/ca-body.json
```

## Paginate through every page

The API uses cursor pagination: pass the previous response's
`pagination.next_cursor` as the `cursor` query parameter and stop once
`pagination.has_next` is `false`. This loop collects every account into a single
JSON array.

```bash theme={null}
collect_all_accounts() {
  local cursor="" page url
  : > /tmp/ca-accounts.jsonl

  while :; do
    url="$CREATORAUDIT_BASE_URL/accounts?limit=200"
    if [ -n "$cursor" ]; then
      url="$url&cursor=$cursor"
    fi

    page=$(curl --silent --show-error --fail \
      --header "Authorization: Bearer $CREATORAUDIT_API_KEY" \
      "$url") || { echo "request failed" >&2; return 1; }

    # append this page's items
    jq --compact-output '.data[]' <<<"$page" >> /tmp/ca-accounts.jsonl

    # stop when the API says there is no next page
    if [ "$(jq --raw-output '.pagination.has_next' <<<"$page")" != "true" ]; then
      break
    fi
    cursor=$(jq --raw-output '.pagination.next_cursor' <<<"$page")
  done

  jq --slurp '.' /tmp/ca-accounts.jsonl
}

collect_all_accounts | jq 'length'
```

<Note>
  `next_cursor` is opaque — don't construct or decode it yourself. Always pass back the
  exact string the previous page returned.
</Note>

## Next steps

* [Introduction](/api-reference/introduction) — auth, base URL, and conventions
* [Pagination](/api-reference/pagination) — the cursor contract in detail
* [Quickstart](/quickstart) — your first request end to end