# Stats & KPI API

Synapse stellt schreibgeschützte Statistiken zu Agenten-Gesundheit, API-Nutzung,
Trends und Fleet-KPIs bereit. Alle Endpoints akzeptieren entweder einen MindKey
(`Authorization: Bearer`) oder ein User-JWT (`requireMindOrUser`).

Bestehende Analytics-Routen (siehe auch die `/stats`-Seite im WebUI):

| Route | Zweck |
| --- | --- |
| `GET /stats/agent` | Übersicht aller Agenten (Zeitfenster: `days`) |
| `GET /stats/agent/comparison` | Agenten-Vergleich |
| `GET /stats/agent/:mindName` | Detailstatistik je Agent |
| `GET /stats/agent/:mindName/health` | Health-Score |
| `GET /stats/agent/:mindName/heatmap` | Aktivitäts-Heatmap |
| `GET /stats/agent/:mindName/sessions` | Session-Tracker |
| `GET /stats/api` | API-Nutzung (global) |
| `GET /stats/trends` | Zeitreihen |
| `GET /stats/chat/response-times` | Chat-Antwortzeiten |
| `GET /stats/a2a/flow` | A2A-Nachrichtenfluss |
| `GET /stats/cron` | Cron-Analytics |
| `GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring` | Dashboard-Aggregate |

## GET /export/kpis

Tidy-Long-Export der Betriebs-KPIs (Task 7418541b). Daten-SSOT ist
`src/db/stats.ts` — die Export-Ebene flacht nur ab, sie misst nichts selbst.

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

| Parameter | Werte | Standard |
| --- | --- | --- |
| `format` | `csv` · `json` · `xlsx` | `json` |
| `days` | `1`–`365` (Zeitfenster für Agent-Overview) | `7` |

Antwort:

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

Tidy-Long-Spalten (in allen Formaten identisch):

| Spalte | Bedeutung |
| --- | --- |
| `kategorie` | KPI-Gruppe: `fleet`, `summary`, `backlog`, `activity`, `team`, `monitoring`, `agent_overview` |
| `metrik` | Geflachteter Metrik-Pfad (z. B. `throughput.done_24h_total`) |
| `wert` | Skalarer Wert (Zahl, Text oder `NULL`, wenn nur `detail` Daten trägt) |
| `einheit` | `value` · `count` · `text` · `json` |
| `zeitstempel` | ISO-8601-Erzeugungszeitstempel des Exports |
| `quelle` | Quellfunktion in `src/db/stats.ts` |
| `detail` | JSON-Payload für Arrays/tiefe Objekte, sonst leer |

Beispiel:

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

Die WebUI-Seite `/stats` rendert denselben Export als drei Download-Buttons
(CSV/JSON/XLSX) in der Sektion „KPI-Export“.