# 統計 & KPI API

Synapseは、エージェントの健全性、API使用状況、トレンド、フリートKPIに関する読み取り専用の統計を公開します。すべてのエンドポイントは、MindKey（`Authorization: Bearer`）またはユーザーJWT（`requireMindOrUser`）を受け付けます。

既存の分析ルート（WebUIの`/stats`ページを参照）：

| ルート | 目的 |
| --- | --- |
| `GET /stats/agent` | 全エージェントの概要（期間：`days`） |
| `GET /stats/agent/comparison` | エージェント間比較 |
| `GET /stats/agent/:mindName` | 1エージェントの詳細統計 |
| `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` | cronの分析 |
| `GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring` | ダッシュボード集計 |

## GET /export/kpis

運用KPIのtidy-longエクスポート（タスク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` | スカラー値（数値、テキスト、または`detail`だけがデータを持つ場合は`NULL`） |
| `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
```

WebUIの`/stats`ページは、同じエクスポートを「KPI export」セクションに3つのダウンロードボタン（CSV/JSON/XLSX）として表示します。