# API de estatísticas e KPI

A Synapse expõe estatísticas somente leitura sobre a saúde dos agentes, uso da API, tendências e KPIs de frota. Todos os endpoints aceitam um MindKey (`Authorization: Bearer`) ou um JWT de usuário (`requireMindOrUser`).

Rotas de análise existentes (ver a página `/stats` na WebUI):

| Rota | Propósito |
| --- | --- |
| `GET /stats/agent` | Visão geral de todos os agentes (período: `days`) |
| `GET /stats/agent/comparison` | Comparação entre agentes |
| `GET /stats/agent/:mindName` | Estatísticas detalhadas de um agente |
| `GET /stats/agent/:mindName/health` | Pontuação de saúde |
| `GET /stats/agent/:mindName/heatmap` | Mapa de calor de atividade |
| `GET /stats/agent/:mindName/sessions` | Rastreador de sessões |
| `GET /stats/api` | Uso da API (global) |
| `GET /stats/trends` | Séries temporais |
| `GET /stats/chat/response-times` | Tempos de resposta do chat |
| `GET /stats/a2a/flow` | Fluxo de mensagens A2A |
| `GET /stats/cron` | Analítica de crons |
| `GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring` | Agregados do painel |

## GET /export/kpis

Exportação tidy-long dos KPIs operacionais (task 7418541b). A fonte da verdade dos dados é `src/db/stats.ts` — a camada de exportação apenas achata, não mede nada por si.

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

| Parâmetro | Valores | Padrão |
| --- | --- | --- |
| `format` | `csv` · `json` · `xlsx` | `json` |
| `days` | `1`–`365` (janela para a visão geral de agentes) | `7` |

Resposta:

- `format=json` → `{ generated_at, period_days, format: "long", columns, row_count, rows[] }`
- `format=csv` → `text/csv; charset=utf-8` (RFC 4180, BOM, CRLF) como anexo
- `format=xlsx` → pasta de trabalho Excel (planilha única `KPIs`) como anexo

Colunas tidy-long (idênticas em todos os formatos):

| Coluna | Significado |
| --- | --- |
| `kategorie` | Grupo de KPI: `fleet`, `summary`, `backlog`, `activity`, `team`, `monitoring`, `agent_overview` |
| `metrik` | Caminho de métrica achatado (ex. `throughput.done_24h_total`) |
| `wert` | Valor escalar (número, texto ou `NULL` quando só `detail` carrega dados) |
| `einheit` | `value` · `count` · `text` · `json` |
| `zeitstempel` | Timestamp ISO-8601 de geração do export |
| `quelle` | Função de origem em `src/db/stats.ts` |
| `detail` | Payload JSON para arrays/objetos profundos, caso contrário vazio |

Exemplo:

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

A página `/stats` da WebUI renderiza o mesmo export como três botões de download (CSV/JSON/XLSX) na seção "KPI export".