# API Statistik & KPI

Synapse memaparkan statistik baca-saja tentang kesehatan agen, penggunaan API, tren, dan KPI armada. Semua endpoint menerima MindKey (`Authorization: Bearer`) atau JWT pengguna (`requireMindOrUser`).

Rute analitik yang ada (lihat halaman `/stats` di WebUI):

| Rute | Tujuan |
| --- | --- |
| `GET /stats/agent` | Tinjauan semua agen (periode: `days`) |
| `GET /stats/agent/comparison` | Perbandingan antar-agen |
| `GET /stats/agent/:mindName` | Statistik terperinci untuk satu agen |
| `GET /stats/agent/:mindName/health` | Skor kesehatan |
| `GET /stats/agent/:mindName/heatmap` | Peta panas aktivitas |
| `GET /stats/agent/:mindName/sessions` | Pelacak sesi |
| `GET /stats/api` | Penggunaan API (global) |
| `GET /stats/trends` | Deret waktu |
| `GET /stats/chat/response-times` | Waktu respons obrolan |
| `GET /stats/a2a/flow` | Aliran pesan A2A |
| `GET /stats/cron` | Analitik cron |
| `GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring` | Agregat dasbor |

## GET /export/kpis

Ekspor tidy-long KPI operasional (task 7418541b). Sumber kebenaran data adalah `src/db/stats.ts` — lapisan ekspor hanya meratakan, ia sendiri tidak mengukur apa pun.

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

| Parameter | Nilai | Default |
| --- | --- | --- |
| `format` | `csv` · `json` · `xlsx` | `json` |
| `days` | `1`–`365` (jendela untuk tinjauan agen) | `7` |

Respons:

- `format=json` → `{ generated_at, period_days, format: "long", columns, row_count, rows[] }`
- `format=csv` → `text/csv; charset=utf-8` (RFC 4180, BOM, CRLF) sebagai lampiran
- `format=xlsx` → Buku kerja Excel (satu lembar `KPIs`) sebagai lampiran

Kolom tidy-long (identik di semua format):

| Kolom | Arti |
| --- | --- |
| `kategorie` | Grup KPI: `fleet`, `summary`, `backlog`, `activity`, `team`, `monitoring`, `agent_overview` |
| `metrik` | Jalur metrik yang diratakan (mis. `throughput.done_24h_total`) |
| `wert` | Nilai skalar (angka, teks, atau `NULL` saat hanya `detail` yang membawa data) |
| `einheit` | `value` · `count` · `text` · `json` |
| `zeitstempel` | Stempel waktu pembuatan ekspor ISO-8601 |
| `quelle` | Fungsi sumber di `src/db/stats.ts` |
| `detail` | Payload JSON untuk array/objek dalam, selain itu kosong |

Contoh:

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

Halaman `/stats` WebUI merender ekspor yang sama sebagai tiga tombol unduh (CSV/JSON/XLSX) di bagian «KPI export».