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

# Visibility Score for one asset

> Get an asset's traffic-weighted Visibility Score for a window and the change vs the prior window.

The headline number on every Visibility tile in the Profound app, plus
the `+1.0 pp` badge beside it. Same call twice — current window and
prior window of equal length — and diff the two scores.

## How this example works

1. **Aggregate, not time-series.** Omit `date` from `dimensions`; filter
   on `asset_name`. Response has one row with a single traffic-weighted
   score.
2. **Run the same call twice** — once for the current window, once for
   the prior window of equal length — then subtract.
3. **Read positions from `info.query.metrics`.** Don't hardcode array
   indices.

<RequestExample>
  ```python Python theme={null}
  import os
  from datetime import date, timedelta
  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>"
  ASSET_NAME    = "<your-asset-name>"
  METRIC        = "visibility_score"   # or share_of_voice, average_position, ...
  DAYS          = 7
  INCLUSIVE_END = date(2026, 5, 11)    # the last day of your current window


  def get_visibility_score(category_id, asset_name, metric, start, end):
      """Aggregate score for one asset in one window."""
      res = client.reports.visibility(
          category_id=category_id,
          start_date=start.isoformat(),
          end_date=end.isoformat(),
          metrics=[metric],
          filters=[{"field": "asset_name", "operator": "is", "value": asset_name}],
      )
      order = res.info.query["metrics"]
      return res.data[0].metrics[order.index(metric)]


  def current_and_prior_windows(inclusive_end, days):
      """Two (start, end_exclusive) pairs of equal length, back-to-back."""
      current = (
          inclusive_end - timedelta(days=days - 1),
          inclusive_end + timedelta(days=1),     # +1 day → exclusive end
      )
      prior = (current[0] - timedelta(days=days), current[0])
      return current, prior


  # Helpers — translate human-readable names into the IDs the report API needs.

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


  def find_asset_name(category_id, name):
      """Return the canonical asset name (case-insensitive) inside the category."""
      for a in client.organizations.categories.assets(category_id):
          if a.name.lower() == name.lower():
              return a.name
      raise ValueError(f"No asset named {name!r} in this category")


  # Resolve names → IDs, then run both windows.
  category_id    = find_category_id(CATEGORY_NAME)
  asset_name     = find_asset_name(category_id, ASSET_NAME)
  current, prior = current_and_prior_windows(INCLUSIVE_END, DAYS)

  current_score = get_visibility_score(category_id, asset_name, METRIC, *current)
  prior_score   = get_visibility_score(category_id, asset_name, METRIC, *prior)
  delta_pp      = (current_score - prior_score) * 100

  print(f"{asset_name} {METRIC}: {current_score:.1%}  ({delta_pp:+.1f} pp vs prev period)")
  ```

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

  # Current window
  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"],
      "filters": [{"field": "asset_name", "operator": "is", "value": "<your-asset-name>"}]
    }'

  # Previous window — same body, prior dates. Diff the two scores client-side.
  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-04-28",
      "end_date": "2026-05-05",
      "metrics": ["visibility_score"],
      "filters": [{"field": "asset_name", "operator": "is", "value": "<your-asset-name>"}]
    }'
  ```
</RequestExample>

## Available metrics

Swap `visibility_score` for any of these to get a different KPI tile:

| Metric             | What it is                                      | Format  | Direction           |
| ------------------ | ----------------------------------------------- | ------- | ------------------- |
| `visibility_score` | Fraction of answers the asset appeared in       | Percent | Higher is better    |
| `share_of_voice`   | Fraction of all mentions the asset accounts for | Percent | Higher is better    |
| `average_position` | Average rank when the asset is mentioned        | Rank    | **Lower** is better |
| `mentions_count`   | Raw count of mentions                           | Number  | Higher is better    |
| `executions`       | Number of prompts run                           | Number  | Higher is better    |

For `average_position`, flip the delta's color logic — a negative `delta`
is an improvement.

## Common follow-ups

<CardGroup cols={2}>
  <Card title="Plot the same metric over time" icon="chart-line" href="/cookbook/visibility/visibility-over-time">
    Add `date` to dimensions to build a daily line chart.
  </Card>

  <Card title="Headline + daily series, together" icon="layer-group" href="/cookbook/visibility/headline-and-daily">
    Why the headline call and the chart call return different numbers.
  </Card>
</CardGroup>