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