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

# Build a creator leaderboard

> Rank your tracked creators by views or engagement and render the result as a table.

This tutorial turns your tracked creators into a ranked leaderboard. You'll pull the top creators for a period, enrich each with its analytics, sort by the metric you care about, and print a table you can drop into a dashboard or report.

<Note>
  Response fields vary by endpoint, so fetch the live shape and read from it rather than
  assuming field names. The [API reference](/api-reference/introduction) covers the
  shared conventions, and you'll need a key from the [API keys
  page](https://app.creatoraudit.com/app/api-keys).
</Note>

<Steps>
  <Step title="Confirm your key">
    `GET /v2/whoami` verifies the key and returns the organization it belongs to. If this
    fails, fix auth before going further — see [API setup](/api-setup).

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

  <Step title="Pull the top creators for a period">
    `GET /v2/creators/top` ranks your creators over a `period` of `7d`, `30d`, or `90d`.
    This is your candidate set for the leaderboard.

    <Warning>
      `GET /v2/creators/top` caps `limit` at **25**. To rank a larger roster, page through
      `GET /v2/creators` (up to 200 per page) and enrich those instead — see the last step.
    </Warning>

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

      ```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,
      )

      top = client.request(
          "GET", "/creators/top", params={"period": "30d", "limit": 25}
      )
      top.raise_for_status()
      creators = top.json()["data"]
      ```
    </CodeGroup>
  </Step>

  <Step title="Enrich each creator with analytics">
    For every creator in the candidate set, call `GET /v2/creators/{id}/analytics` to get
    its metrics. Read the fields you need from the live response — views, likes, comments,
    shares, followers — and compute engagement rate as
    `(likes + comments + shares) / views` when you want to rank by engagement.

    <CodeGroup>
      ```bash curl theme={null}
      # Repeat per creator id from the previous step
      curl "https://api.creatoraudit.com/v2/creators/CREATOR_ID/analytics?start_date=2026-05-16&end_date=2026-06-15" \
        -H "Authorization: Bearer YOUR_API_KEY"
      ```

      ```python python theme={null}
      def engagement_rate(m: dict) -> float:
          views = m.get("views") or 0
          if not views:
              return 0.0
          return (m.get("likes", 0) + m.get("comments", 0) + m.get("shares", 0)) / views


      rows = []
      for creator in creators:
          creator_id = creator["id"]
          resp = client.request("GET", f"/creators/{creator_id}/analytics")
          resp.raise_for_status()
          # Read the live shape; analytics payloads carry the metric totals you sort on.
          metrics = resp.json()["data"]
          rows.append({"creator": creator, "metrics": metrics})
      ```
    </CodeGroup>
  </Step>

  <Step title="Rank and render the table">
    Sort by whichever metric matters — raw `views` for reach, or engagement rate for
    quality — then print a table. Keep the sort key configurable so the same code powers a
    "most viewed" and a "most engaging" board.

    ```python theme={null}
    def sort_value(row: dict, key: str) -> float:
        m = row["metrics"]
        if key == "engagement":
            return engagement_rate(m)
        return float(m.get(key, 0) or 0)

    ranked = sorted(rows, key=lambda r: sort_value(r, "views"), reverse=True)

    print(f"{'#':>3}  {'creator':<24} {'views':>12} {'eng. rate':>10}")
    for i, row in enumerate(ranked, start=1):
        name = row["creator"].get("name") or row["creator"]["id"]
        views = int(row["metrics"].get("views", 0) or 0)
        rate = engagement_rate(row["metrics"])
        print(f"{i:>3}  {name:<24} {views:>12,} {rate:>9.2%}")

    client.close()
    ```
  </Step>
</Steps>

<Note>
  A creator added recently may have `last_scrape_time: null` and little or no history
  until its first refresh lands, so it can sort low through no fault of its own. See
  [Data freshness](/data-freshness) for the timing.
</Note>

## Widen coverage beyond 25

`GET /v2/creators/top` is bounded at 25 results. To leaderboard your whole roster, page
through `GET /v2/creators` (cursor pagination, `limit` up to 200) to collect every creator
id, then run the same enrich-and-sort loop over the full list. Read
`pagination.has_next` and pass the previous `pagination.next_cursor` back as `cursor` until
`has_next` is `false`.

<Columns cols={2}>
  <Card title="Pagination" href="/api-reference/pagination">
    The cursor contract for walking `/v2/creators` past the first page.
  </Card>

  <Card title="Python client" href="/examples/python">
    A typed client with a ready-made pagination helper.
  </Card>

  <Card title="Creators dashboard" href="/dashboard/creators">
    The same rankings, rendered in the app.
  </Card>
</Columns>