Skip to main content
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"
1

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"
  }
}
2

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 }
}
3

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'

​
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