# Statistik- & KPI-API

Synapse exponerar skrivskyddad statistik om agenthälsa, API-användning, trender och fleet-KPI:er. Alla endpoints tar emot antingen en MindKey (`Authorization: Bearer`) eller en användar-JWT (`requireMindOrUser`).

Befintliga analysrutter (se `/stats`-sidan i WebUI):

| Rutt | Syfte |
| --- | --- |
| `GET /stats/agent` | Översikt av alla agenter (period: `days`) |
| `GET /stats/agent/comparison` | Jämförelse mellan agenter |
| `GET /stats/agent/:mindName` | Detaljerad statistik för en agent |
| `GET /stats/agent/:mindName/health` | Hälsopoäng |
| `GET /stats/agent/:mindName/heatmap` | Aktivitets-värmekarta |
| `GET /stats/agent/:mindName/sessions` | Sessinspårare |
| `GET /stats/api` | API-användning (global) |
| `GET /stats/trends` | Tidsserier |
| `GET /stats/chat/response-times` | Svars tider för chat |
| `GET /stats/a2a/flow` | A2A-meddelandeflöde |
| `GET /stats/cron` | Cron-analys |
| `GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring` | Panelaggregat |

## GET /export/kpis

Tidy-long-export av operativa KPI:er (task 7418541b). Datans källa av sanning är `src/db/stats.ts` — exportlagret plattar bara ut, det mäter inget själv.

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

| Parameter | Värden | Standard |
| --- | --- | --- |
| `format` | `csv` · `json` · `xlsx` | `json` |
| `days` | `1`–`365` (fönster för agentöversikt) | `7` |

Svar:

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

Tidy-long-kolumner (identiska i alla format):

| Kolumn | Betydelse |
| --- | --- |
| `kategorie` | KPI-grupp: `fleet`, `summary`, `backlog`, `activity`, `team`, `monitoring`, `agent_overview` |
| `metrik` | Utplattad metrik-sökväg (t.ex. `throughput.done_24h_total`) |
| `wert` | Skalärt värde (tal, text eller `NULL` när endast `detail` bär data) |
| `einheit` | `value` · `count` · `text` · `json` |
| `zeitstempel` | ISO-8601-genereringstidsstämpel för exporten |
| `quelle` | Källfunktion i `src/db/stats.ts` |
| `detail` | JSON-nyttolast för arrayer/djupa objekt, annars tom |

Exempel:

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

WebUI-sidan `/stats` renderar samma export som tre nedladdningsknappar (CSV/JSON/XLSX) i avsnittet "KPI export".