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.

Python

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%}")

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 recipe — it returns the set of asset names flagged is_owned in this category.