> ## 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 de un activo

> Obtén el Visibility Score ponderado por tráfico de un activo para un periodo y el cambio respecto al periodo anterior.

El número principal de cada tarjeta de Visibility en la app de Profound, junto
con la insignia `+1.0 pp` que aparece a su lado. Haz la misma llamada dos veces
(periodo actual y periodo anterior de igual duración) y calcula la diferencia
entre ambas puntuaciones.

## Cómo funciona este ejemplo

1. **Agregado, no serie temporal.** Omite `date` de `dimensions`; filtra
   por `asset_name`. La respuesta tiene una sola fila con una única
   puntuación ponderada por tráfico.
2. **Ejecuta la misma llamada dos veces** (una para el periodo actual y otra
   para el periodo anterior de igual duración) y luego resta.
3. **Lee las posiciones desde `info.query.metrics`.** No codifiques de forma
   fija los índices del array.

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

## Métricas disponibles

Sustituye `visibility_score` por cualquiera de estas para obtener una tarjeta de KPI diferente:

| Métrica | Qué es | Formato | Dirección |
| - | - | - | - |
| `visibility_score` | Fracción de respuestas en las que apareció el activo | Porcentaje | Mayor es mejor |
| `share_of_voice` | Fracción del total de menciones que corresponde al activo | Porcentaje | Mayor es mejor |
| `average_position` | Posición media cuando se menciona el activo | Posición | **Menor** es mejor |
| `mentions_count` | Recuento bruto de menciones | Número | Mayor es mejor |
| `executions` | Número de prompts ejecutados | Número | Mayor es mejor |

Para `average_position`, invierte la lógica de color de la variación: un `delta`
negativo es una mejora.

## Siguientes pasos habituales

<CardGroup cols={2}>
  <Card title="Representa la misma métrica a lo largo del tiempo" icon="chart-line" href="/es/cookbook/visibility/visibility-over-time">
    Añade `date` a las dimensiones para crear un gráfico de líneas diario.
  </Card>

  <Card title="Cifra principal y serie diaria, juntas" icon="layer-group" href="/es/cookbook/visibility/headline-and-daily">
    Por qué la llamada de la cifra principal y la del gráfico devuelven números distintos.
  </Card>
</CardGroup>