> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Top-N leaderboard

> Rank every asset in a category by any visibility metric.

The leaderboard on the Visibility tile is the same aggregate call as the
headline, without the asset filter. The API returns one row per asset, and
you sort client-side.

## How this example works

1. **Add `asset_name` to dimensions, drop the filter.** Now every asset gets
   its own row.
2. **Sort client-side.** The API returns rows in the order it computed them
   (typically sorted by the first metric descending); always re-sort in your
   code to be deterministic. Use `reverse=True` for "higher is better" metrics
   like `visibility_score`, and `reverse=False` for `average_position`
   (lower rank = better).
3. **`pagination.limit`.** The default is 100. Set it higher (max 50,000) if
   your category has many assets.

<RequestExample>
  ```python Python theme={null}
  import os
  from profound import Profound

  client = Profound(api_key=os.environ["PROFOUND_API_KEY"])

  # What to fetch — replace with your own values.
  CATEGORY_NAME = "<your-category-name>"
  START_DATE    = "2026-05-05"
  END_DATE      = "2026-05-12"   # exclusive — returns data through 2026-05-11
  METRIC        = "visibility_score"   # or share_of_voice, average_position, ...
  TOP_N         = 10


  def get_leaderboard(category_id, metric, start_date, end_date):
      """All assets in the category ranked by the chosen metric."""
      res = client.reports.visibility(
          category_id=category_id,
          start_date=start_date,
          end_date=end_date,
          metrics=[metric],
          dimensions=["asset_name"],
          pagination={"limit": 50000, "offset": 0},
      )
      m_order = res.info.query["metrics"]
      d_order = res.info.query["dimensions"]
      i_metric = m_order.index(metric)
      i_asset  = d_order.index("asset_name")

      # Lower-is-better for average_position; higher-is-better for everything else.
      reverse = metric != "average_position"
      return sorted(
          [(row.dimensions[i_asset], row.metrics[i_metric]) for row in res.data],
          key=lambda x: x[1],
          reverse=reverse,
      )


  # Helper — translate the category name to the UUID the report API expects.

  def find_category_id(name):
      """Return the UUID of the category whose name matches (case-insensitive)."""
      for c in client.organizations.categories.list():
          if c.name.lower() == name.lower():
              return c.id
      raise ValueError(f"No category named {name!r}")


  # Resolve name → ID, then run.
  category_id = find_category_id(CATEGORY_NAME)
  leaderboard = get_leaderboard(category_id, METRIC, START_DATE, END_DATE)

  for rank, (name, value) in enumerate(leaderboard[:TOP_N], start=1):
      print(f"{rank:>2}. {name:<24} {value:.1%}")
  ```

  ```bash curl theme={null}
  export PROFOUND_API_KEY=your_api_key_here

  curl -X POST "https://api.tryprofound.com/v1/reports/visibility" \
    -H "X-API-Key: $PROFOUND_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "category_id": "your-category-uuid",
      "start_date": "2026-05-05",
      "end_date": "2026-05-12",
      "metrics": ["visibility_score"],
      "dimensions": ["asset_name"],
      "pagination": {"limit": 50000, "offset": 0}
    }'
  ```
</RequestExample>

## Highlighting your owned assets

To mark your own assets in the leaderboard (the "Owned" tag in the Profound
UI), join the response against the
[List your owned assets](/cookbook/setup/list-owned-assets) recipe: it
returns the set of asset names flagged `is_owned` in this category.