# API статистики та KPI

Synapse віддає статистику в режимі лише для читання: здоров'я агентів, використання API, тренди та KPI флоту. Усі ендпоінти приймають або MindKey (`Authorization: Bearer`), або користувацький JWT (`requireMindOrUser`).

Наявні аналітичні маршрути (див. сторінку `/stats` у WebUI):

| Маршрут | Призначення |
| --- | --- |
| `GET /stats/agent` | Огляд усіх агентів (період: `days`) |
| `GET /stats/agent/comparison` | Порівняння між агентами |
| `GET /stats/agent/:mindName` | Детальна статистика одного агента |
| `GET /stats/agent/:mindName/health` | Оцінка здоров'я |
| `GET /stats/agent/:mindName/heatmap` | Теплова карта активності |
| `GET /stats/agent/:mindName/sessions` | Трекер сесій |
| `GET /stats/api` | Використання API (глобально) |
| `GET /stats/trends` | Часові ряди |
| `GET /stats/chat/response-times` | Час відповіді в чаті |
| `GET /stats/a2a/flow` | Потік повідомлень A2A |
| `GET /stats/cron` | Аналітика кронів |
| `GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring` | Зведені показники дашборда |

## GET /export/kpis

Tidy-long експорт операційних KPI (task 7418541b). Джерело правди даних — `src/db/stats.ts`: шар експорту лише вирівнює, сам нічого не вимірює.

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

| Параметр | Значення | За замовчуванням |
| --- | --- | --- |
| `format` | `csv` · `json` · `xlsx` | `json` |
| `days` | `1`–`365` (вікно для огляду агентів) | `7` |

Відповідь:

- `format=json` → `{ generated_at, period_days, format: "long", columns, row_count, rows[] }`
- `format=csv` → `text/csv; charset=utf-8` (RFC 4180, BOM, CRLF) вкладенням
- `format=xlsx` → книга Excel (єдиний аркуш `KPIs`) вкладенням

Tidy-long колонки (ідентичні в усіх форматах):

| Колонка | Значення |
| --- | --- |
| `kategorie` | Група KPI: `fleet`, `summary`, `backlog`, `activity`, `team`, `monitoring`, `agent_overview` |
| `metrik` | Вирівняний шлях метрики (напр. `throughput.done_24h_total`) |
| `wert` | Скалярне значення (число, текст або `NULL`, коли дані несе лише `detail`) |
| `einheit` | `value` · `count` · `text` · `json` |
| `zeitstempel` | Тимчасова мітка генерації експорту ISO-8601 |
| `quelle` | Вихідна функція в `src/db/stats.ts` |
| `detail` | JSON-навантаження для масивів/глибоких об'єктів, інакше порожньо |

Приклад:

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

Сторінка `/stats` WebUI рендерить той самий експорт у вигляді трьох кнопок завантаження (CSV/JSON/XLSX) у розділі «KPI export».