# API de estadísticas y KPI

Synapse expone estadísticas de solo lectura sobre la salud de los agentes, el uso de la API, las tendencias y los KPIs de flota. Todos los endpoints aceptan un MindKey (`Authorization: Bearer`) o un JWT de usuario (`requireMindOrUser`).

Rutas de análisis existentes (ver la página `/stats` en la WebUI):

| Ruta | Propósito |
| --- | --- |
| `GET /stats/agent` | Vista general de todos los agentes (período: `days`) |
| `GET /stats/agent/comparison` | Comparación entre agentes |
| `GET /stats/agent/:mindName` | Estadísticas detalladas de un agente |
| `GET /stats/agent/:mindName/health` | Puntuación de salud |
| `GET /stats/agent/:mindName/heatmap` | Mapa de calor de actividad |
| `GET /stats/agent/:mindName/sessions` | Rastreador de sesiones |
| `GET /stats/api` | Uso de la API (global) |
| `GET /stats/trends` | Series temporales |
| `GET /stats/chat/response-times` | Tiempos de respuesta del chat |
| `GET /stats/a2a/flow` | Flujo de mensajes A2A |
| `GET /stats/cron` | Analítica de cron |
| `GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring` | Agregados del panel |

## GET /export/kpis

Exportación tidy-long de los KPIs operativos (tarea 7418541b). La fuente de verdad de los datos es `src/db/stats.ts` — la capa de exportación solo aplana, no mide nada por sí misma.

```
GET /export/kpis?format=csv|json|xlsx&days=7
```

| Parámetro | Valores | Predeterminado |
| --- | --- | --- |
| `format` | `csv` · `json` · `xlsx` | `json` |
| `days` | `1`–`365` (ventana para la vista general de agentes) | `7` |

Respuesta:

- `format=json` → `{ generated_at, period_days, format: "long", columns, row_count, rows[] }`
- `format=csv` → `text/csv; charset=utf-8` (RFC 4180, BOM, CRLF) como adjunto
- `format=xlsx` → libro de Excel (hoja única `KPIs`) como adjunto

Columnas tidy-long (idénticas en todos los formatos):

| Columna | Significado |
| --- | --- |
| `kategorie` | Grupo de KPI: `fleet`, `summary`, `backlog`, `activity`, `team`, `monitoring`, `agent_overview` |
| `metrik` | Ruta de métrica aplanada (p. ej. `throughput.done_24h_total`) |
| `wert` | Valor escalar (número, texto o `NULL` cuando solo `detail` lleva datos) |
| `einheit` | `value` · `count` · `text` · `json` |
| `zeitstempel` | Marca de tiempo ISO-8601 de generación del export |
| `quelle` | Función de origen en `src/db/stats.ts` |
| `detail` | Payload JSON para arrays/objetos profundos, de lo contrario vacío |

Ejemplo:

```bash
curl -s -H "Authorization: Bearer $MIND_KEY" \
  "https://synapse.schaefer.zone/export/kpis?format=csv&days=7" -o kpis.csv
```

La página `/stats` de la WebUI renderiza el mismo export como tres botones de descarga (CSV/JSON/XLSX) en la sección "KPI export".