cURL

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 to parse JSON. Pair them to script anything from a one-off check to a full paginated export.

Create a key on the API keys page, 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.

Setup

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

export CREATORAUDIT_API_KEY="YOUR_API_KEY"
export CREATORAUDIT_BASE_URL="https://api.creatoraudit.com/v2"

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.

curl --silent --show-error \
  --header "Authorization: Bearer $CREATORAUDIT_API_KEY" \
  "$CREATORAUDIT_BASE_URL/whoami" | jq

Response

{
  "data": {
    "type": "whoami",
    "organization_id": "org_2a...",
    "api_key_name": "ci-export"
  }
}

List tracked accounts

GET /accounts returns a page of the accounts your organization tracks. Control page size with limit (1–200).

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 for the full contract.

Response

{
  "data": [{ "id": "...", "platform": "tiktok", "username": "creatoraudit" }],
  "pagination": { "next_cursor": "eyJ2IjoxfQ", "has_next": true, "limit": 25 }
}

Track an account

POST /accounts starts tracking a new account. The body requires platform (instagram or tiktok) and username.

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'

More requests

# period accepts 7d | 30d | 90d
curl --silent --show-error \
  --header "Authorization: Bearer $CREATORAUDIT_API_KEY" \
  "$CREATORAUDIT_BASE_URL/overview?period=30d" | jq '.data'

# 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

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

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.

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

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.

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'

next_cursor is opaque — don’t construct or decode it yourself. Always pass back the exact string the previous page returned.

Next steps

Introduction — auth, base URL, and conventions
Pagination — the cursor contract in detail
Quickstart — your first request end to end

Getting started

MCP & AI agents

Using the API

Web dashboard

Tutorials

Help

Appendix

Setup

More requests

Reading `X-Request-ID`

Handling errors

Paginate through every page

Next steps

​Setup

​More requests

​Reading X-Request-ID

​Handling errors

​Paginate through every page

​Next steps

Setup

More requests

Reading `X-Request-ID`

Handling errors

Paginate through every page

Next steps