# Stats & KPI API

Synapse exposes read-only statistics for agent health, API usage, trends and
fleet KPIs. All endpoints accept either a MindKey (`Authorization: Bearer`)
or a user JWT (`requireMindOrUser`).

Existing analytics routes (see the `/stats` page in the WebUI):

| Route | Purpose |
| --- | --- |
| `GET /stats/agent` | All agents overview (period: `days`) |
| `GET /stats/agent/comparison` | Cross-agent comparison |
| `GET /stats/agent/:mindName` | Detailed stats for one agent |
| `GET /stats/agent/:mindName/health` | Health score |
| `GET /stats/agent/:mindName/heatmap` | Activity heatmap |
| `GET /stats/agent/:mindName/sessions` | Session tracker |
| `GET /stats/api` | API usage (global) |
| `GET /stats/trends` | Time series |
| `GET /stats/chat/response-times` | Chat response times |
| `GET /stats/a2a/flow` | A2A message flow |
| `GET /stats/cron` | Cron analytics |
| `GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring` | Dashboard aggregates |

## GET /export/kpis

Tidy-long export of the operational KPIs (task 7418541b). The data source of
truth is `src/db/stats.ts` — the export layer only flattens, it measures
nothing itself.

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

| Parameter | Values | Default |
| --- | --- | --- |
| `format` | `csv` · `json` · `xlsx` | `json` |
| `days` | `1`–`365` (window for agent overview) | `7` |

Response:

- `format=json` → `{ generated_at, period_days, format: "long", columns, row_count, rows[] }`
- `format=csv` → `text/csv; charset=utf-8` (RFC 4180, BOM, CRLF) as attachment
- `format=xlsx` → Excel workbook (single sheet `KPIs`) as attachment

Tidy-long columns (identical in all formats):

| Column | Meaning |
| --- | --- |
| `kategorie` | KPI group: `fleet`, `summary`, `backlog`, `activity`, `team`, `monitoring`, `agent_overview` |
| `metrik` | Flattened metric path (e.g. `throughput.done_24h_total`) |
| `wert` | Scalar value (number, text or `NULL` when only `detail` carries data) |
| `einheit` | `value` · `count` · `text` · `json` |
| `zeitstempel` | ISO-8601 generation timestamp of the export |
| `quelle` | Source function in `src/db/stats.ts` |
| `detail` | JSON payload for arrays/deep objects, otherwise empty |

Example:

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

The WebUI `/stats` page renders the same export as three download buttons
(CSV/JSON/XLSX) in the "KPI export" section.