# Statistieken & KPI-API

Synapse stelt alleen-lezen statistieken bloot over agent-gezondheid, API-gebruik, trends en fleet-KPI's. Alle endpoints accepteren een MindKey (`Authorization: Bearer`) of een gebruikers-JWT (`requireMindOrUser`).

Bestaande analytics-routes (zie de pagina `/stats` in de WebUI):

| Route | Doel |
| --- | --- |
| `GET /stats/agent` | Overzicht van alle agenten (periode: `days`) |
| `GET /stats/agent/comparison` | Vergelijking tussen agenten |
| `GET /stats/agent/:mindName` | Gedetailleerde statistieken voor één agent |
| `GET /stats/agent/:mindName/health` | Gezondheidsscore |
| `GET /stats/agent/:mindName/heatmap` | Activiteit-heatmap |
| `GET /stats/agent/:mindName/sessions` | Sessietracker |
| `GET /stats/api` | API-gebruik (globaal) |
| `GET /stats/trends` | Tijdreeksen |
| `GET /stats/chat/response-times` | Chat-responstijden |
| `GET /stats/a2a/flow` | A2A-berichtstroom |
| `GET /stats/cron` | Cron-analyse |
| `GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring` | Dashboard-aggregaten |

## GET /export/kpis

Tidy-long-export van de operationele KPI's (task 7418541b). De databron van de waarheid is `src/db/stats.ts` — de exportlaag plattet alleen, hij meet zelf niets.

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

| Parameter | Waarden | Standaard |
| --- | --- | --- |
| `format` | `csv` · `json` · `xlsx` | `json` |
| `days` | `1`–`365` (venster voor agent-overzicht) | `7` |

Reactie:

- `format=json` → `{ generated_at, period_days, format: "long", columns, row_count, rows[] }`
- `format=csv` → `text/csv; charset=utf-8` (RFC 4180, BOM, CRLF) als bijlage
- `format=xlsx` → Excel-werkboek (enkel blad `KPIs`) als bijlage

Tidy-long-kolommen (identiek in alle formaten):

| Kolom | Betekenis |
| --- | --- |
| `kategorie` | KPI-groep: `fleet`, `summary`, `backlog`, `activity`, `team`, `monitoring`, `agent_overview` |
| `metrik` | Geplattete metriek-pad (bijv. `throughput.done_24h_total`) |
| `wert` | Scalaire waarde (getal, tekst of `NULL` wanneer alleen `detail` data bevat) |
| `einheit` | `value` · `count` · `text` · `json` |
| `zeitstempel` | ISO-8601-generatietijdstip van de export |
| `quelle` | Bronfunctie in `src/db/stats.ts` |
| `detail` | JSON-payload voor arrays/diepe objecten, anders leeg |

Voorbeeld:

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

De WebUI-pagina `/stats` rendert dezelfde export als drie downloadknoppen (CSV/JSON/XLSX) in de sectie "KPI export".