# Métricas

Datos agregados de visibilidad, Share of Voice, citaciones y posiciones de tu marca y sus competidores, listos para representar en gráficos. Todos los endpoints aceptan los filtros comunes y el parámetro `output` descrito en Conceptos básicos.

### GET `/metrics/timeseries`

Devuelve series temporales de una o más métricas, agrupadas por actor (tu proyecto + los competidores seleccionados). Los valores semanales y mensuales siguen la semántica de períodos descrita más arriba. Los filtros opcionales `prompt_type` (intención de búsqueda) y `brand_kind` acotan cada métrica a una categoría de prompt.

### GET `/metrics/summary`

Agrega por actor y métrica (`total`/`min`/`max`/`last`). Ideal para tarjetas KPI.

### GET `/metrics/prompt_summary`

Devuelve métricas agregadas por prompt y paginadas (responses, mentions, citations, mention_rate, citation_rate, avg_mention_position, avg_position). Admite `breakdown=model` para añadir la dimensión de modelo de IA a cada fila, devolviendo métricas por prompt y por modelo. Parámetros: `sort` (`responses`, `mentions`, `citations`, `mention_rate` o `visibility`, `citation_rate`, `avg_mention_position`, `avg_position`), `sort_dir` (`asc`/`desc`), `breakdown` (`model`), `page`, `per_page` (máx. 100).

### GET `/metrics/sov`

Share of Voice basado en menciones, alineado con el resumen.

- **over_time**: para cada fecha, `SOV = (actor_mentions / sum_all_mentions) × 100`. Si la suma diaria es 0, se arrastra el último valor (sticky).
- **current**: usa la fecha más reciente con total distinto de cero; si no hay ninguna, usa los totales de todo el rango.
- **breakdown**: los 4 principales actores + una fila agregada _Others_ (y una lista detallada `others`).

### GET `/metrics/top_sources`

Ordena los dominios de fuentes por número de respuestas y tasa media de mención (% de ejecuciones en las que apareció ese dominio).

- El conjunto de datos incluye fuentes no rechazadas vinculadas a ejecuciones de prompts dentro del período y los filtros actuales.
- `total_responses`: número de ejecuciones de prompt únicas que produjeron al menos una fuente en ese dominio.
- `avg_mention_rate` (también se devuelve como `avg_visibility`): `(número de filas de fuentes del dominio / total de ejecuciones) × 100`.
- Ordenación: `sort=total_responses` (por defecto), `sort=avg_mention_rate` o `sort=avg_visibility`.
- Paginación: `page` (>=1), `per_page` (por defecto 20, máximo 100).
- Filtra por dominio: `query` (`LIKE` sin distinguir mayúsculas), p. ej. `query=github`.

Acceso completo. Cancela cuando quieras.