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

# Track a competitor set

> Group competitor handles under one creator, start tracking each account, and compare them over time.

This tutorial sets up a competitor watch list: you'll create a creator to act as the
group, start tracking each competitor's account, link the accounts to the group, and then
compare the whole set over time with a single timeseries call.

<Note>
  Read fields off the live responses rather than assuming names — created resources
  return the `id` you'll need for the next step. You'll need an API key first — see [API
  setup](/api-setup) or create one on the [API keys
  page](https://app.creatoraudit.com/app/api-keys).
</Note>

<Steps>
  <Step title="Create the competitor group">
    `POST /v2/creators` makes the group you'll attach competitors to. Send an
    `Idempotency-Key` so a retry doesn't create a duplicate group, and read the new
    creator's `id` from the response.

    <CodeGroup>
      ```bash curl theme={null}
      curl -X POST "https://api.creatoraudit.com/v2/creators" \
        -H "Authorization: Bearer YOUR_API_KEY" \
        -H "Content-Type: application/json" \
        -H "Idempotency-Key: competitor-set-2026-q2" \
        -d '{ "name": "Competitor set" }'
      ```

      ```python python theme={null}
      import os

      import httpx

      BASE_URL = "https://api.creatoraudit.com/v2"
      client = httpx.Client(
          base_url=BASE_URL,
          headers={"Authorization": f"Bearer {os.environ['CREATORAUDIT_API_KEY']}"},
          timeout=30.0,
      )

      created = client.request(
          "POST",
          "/creators",
          headers={"Idempotency-Key": "competitor-set-2026-q2"},
          json={"name": "Competitor set"},
      )
      created.raise_for_status()
      creator_id = created.json()["data"]["id"]
      ```
    </CodeGroup>
  </Step>

  <Step title="Track each competitor account">
    `POST /v2/accounts` takes a `platform` (`instagram` or `tiktok`) and a `username`. Call
    it once per competitor handle, each with its own `Idempotency-Key` keyed to the handle,
    and read each new account `id` from the response.

    <CodeGroup>
      ```bash curl 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: track-instagram-rival_one" \
        -d '{ "platform": "instagram", "username": "rival_one" }'
      ```

      ```python python theme={null}
      competitors = [
          ("instagram", "rival_one"),
          ("tiktok", "rival_two"),
          ("instagram", "rival_three"),
      ]

      account_ids = []
      for platform, username in competitors:
          resp = client.request(
              "POST",
              "/accounts",
              headers={"Idempotency-Key": f"track-{platform}-{username}"},
              json={"platform": platform, "username": username},
          )
          resp.raise_for_status()
          account_ids.append(resp.json()["data"]["id"])
      ```
    </CodeGroup>
  </Step>

  <Step title="Link the accounts to the group">
    `PUT /v2/creators/{id}/accounts/{account_id}` attaches an account to the group. Call it
    once per account id you collected.

    <CodeGroup>
      ```bash curl theme={null}
      curl -X PUT "https://api.creatoraudit.com/v2/creators/CREATOR_ID/accounts/ACCOUNT_ID" \
        -H "Authorization: Bearer YOUR_API_KEY"
      ```

      ```python python theme={null}
      for account_id in account_ids:
          link = client.request(
              "PUT", f"/creators/{creator_id}/accounts/{account_id}"
          )
          link.raise_for_status()
      ```
    </CodeGroup>

    <Tip>
      To remove a competitor later, `DELETE /v2/creators/{id}/accounts/{account_id}` detaches
      the account from the group without deleting the account itself.
    </Tip>
  </Step>

  <Step title="Compare the set over time">
    `GET /v2/creators/{id}/analytics/timeseries` returns the group's metrics as a time
    series. Pass a `period` of `7d`, `30d`, or `90d` — or `period=custom` with `start_date`
    and `end_date` — and read the series off the live response to chart the competitor set
    against your own.

    <CodeGroup>
      ```bash curl theme={null}
      curl "https://api.creatoraudit.com/v2/creators/CREATOR_ID/analytics/timeseries?period=30d" \
        -H "Authorization: Bearer YOUR_API_KEY"
      ```

      ```python python theme={null}
      series = client.request(
          "GET",
          f"/creators/{creator_id}/analytics/timeseries",
          params={"period": "30d"},
      )
      series.raise_for_status()
      points = series.json()["data"]
      print(f"{len(points)} data points")
      client.close()
      ```
    </CodeGroup>
  </Step>
</Steps>

<Note>
  A freshly tracked account starts with `last_scrape_time: null` and no metrics until
  its first refresh lands — so the timeseries will be sparse right after you set up the
  group, then fill in over the following scrape cycles. See [Data
  freshness](/data-freshness) for the timing before you read too much into an empty
  chart.
</Note>

<Columns cols={2}>
  <Card title="Data freshness" href="/data-freshness">
    Why a new competitor's metrics lag, and when they appear.
  </Card>

  <Card title="Concepts" href="/concepts">
    How creators, accounts, and metrics relate.
  </Card>

  <Card title="Creators dashboard" href="/dashboard/creators">
    Manage the same groups in the app.
  </Card>
</Columns>