{"title":"Stats & KPI API","slug":"stats","category":"api","summary":"Statistik-Endpoints, Fleet-KPIs und Tidy-Long-KPI-Export (CSV/JSON/XLSX) für LLM-Agenten.","audience":["human"],"tags":[],"word_count":260,"read_minutes":1,"lang":"de","translated":true,"requested_lang":"de","content_markdown":"\n# Stats & KPI API\n\nSynapse stellt schreibgeschützte Statistiken zu Agenten-Gesundheit, API-Nutzung,\nTrends und Fleet-KPIs bereit. Alle Endpoints akzeptieren entweder einen MindKey\n(`Authorization: Bearer`) oder ein User-JWT (`requireMindOrUser`).\n\nBestehende Analytics-Routen (siehe auch die `/stats`-Seite im WebUI):\n\n| Route | Zweck |\n| --- | --- |\n| `GET /stats/agent` | Übersicht aller Agenten (Zeitfenster: `days`) |\n| `GET /stats/agent/comparison` | Agenten-Vergleich |\n| `GET /stats/agent/:mindName` | Detailstatistik je Agent |\n| `GET /stats/agent/:mindName/health` | Health-Score |\n| `GET /stats/agent/:mindName/heatmap` | Aktivitäts-Heatmap |\n| `GET /stats/agent/:mindName/sessions` | Session-Tracker |\n| `GET /stats/api` | API-Nutzung (global) |\n| `GET /stats/trends` | Zeitreihen |\n| `GET /stats/chat/response-times` | Chat-Antwortzeiten |\n| `GET /stats/a2a/flow` | A2A-Nachrichtenfluss |\n| `GET /stats/cron` | Cron-Analytics |\n| `GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring` | Dashboard-Aggregate |\n\n## GET /export/kpis\n\nTidy-Long-Export der Betriebs-KPIs (Task 7418541b). Daten-SSOT ist\n`src/db/stats.ts` — die Export-Ebene flacht nur ab, sie misst nichts selbst.\n\n```\nGET /export/kpis?format=csv|json|xlsx&days=7\n```\n\n| Parameter | Werte | Standard |\n| --- | --- | --- |\n| `format` | `csv` · `json` · `xlsx` | `json` |\n| `days` | `1`–`365` (Zeitfenster für Agent-Overview) | `7` |\n\nAntwort:\n\n- `format=json` → `{ generated_at, period_days, format: \"long\", columns, row_count, rows[] }`\n- `format=csv` → `text/csv; charset=utf-8` (RFC 4180, BOM, CRLF) als Anhang\n- `format=xlsx` → Excel-Arbeitsmappe (ein Sheet `KPIs`) als Anhang\n\nTidy-Long-Spalten (in allen Formaten identisch):\n\n| Spalte | Bedeutung |\n| --- | --- |\n| `kategorie` | KPI-Gruppe: `fleet`, `summary`, `backlog`, `activity`, `team`, `monitoring`, `agent_overview` |\n| `metrik` | Geflachteter Metrik-Pfad (z. B. `throughput.done_24h_total`) |\n| `wert` | Skalarer Wert (Zahl, Text oder `NULL`, wenn nur `detail` Daten trägt) |\n| `einheit` | `value` · `count` · `text` · `json` |\n| `zeitstempel` | ISO-8601-Erzeugungszeitstempel des Exports |\n| `quelle` | Quellfunktion in `src/db/stats.ts` |\n| `detail` | JSON-Payload für Arrays/tiefe Objekte, sonst leer |\n\nBeispiel:\n\n```bash\ncurl -s -H \"Authorization: Bearer $MIND_KEY\" \\\n  \"https://synapse.schaefer.zone/export/kpis?format=csv&days=7\" -o kpis.csv\n```\n\nDie WebUI-Seite `/stats` rendert denselben Export als drei Download-Buttons\n(CSV/JSON/XLSX) in der Sektion „KPI-Export“.\n","content_html":"<h1>Stats &amp; KPI API</h1>\n<p>Synapse stellt schreibgeschützte Statistiken zu Agenten-Gesundheit, API-Nutzung,\nTrends und Fleet-KPIs bereit. Alle Endpoints akzeptieren entweder einen MindKey\n(<code>Authorization: Bearer</code>) oder ein User-JWT (<code>requireMindOrUser</code>).</p>\n<p>Bestehende Analytics-Routen (siehe auch die <code>/stats</code>-Seite im WebUI):</p>\n<table>\n<thead>\n<tr>\n<th>Route</th>\n<th>Zweck</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>GET /stats/agent</code></td>\n<td>Übersicht aller Agenten (Zeitfenster: <code>days</code>)</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/comparison</code></td>\n<td>Agenten-Vergleich</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName</code></td>\n<td>Detailstatistik je Agent</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName/health</code></td>\n<td>Health-Score</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName/heatmap</code></td>\n<td>Aktivitäts-Heatmap</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName/sessions</code></td>\n<td>Session-Tracker</td>\n</tr>\n<tr>\n<td><code>GET /stats/api</code></td>\n<td>API-Nutzung (global)</td>\n</tr>\n<tr>\n<td><code>GET /stats/trends</code></td>\n<td>Zeitreihen</td>\n</tr>\n<tr>\n<td><code>GET /stats/chat/response-times</code></td>\n<td>Chat-Antwortzeiten</td>\n</tr>\n<tr>\n<td><code>GET /stats/a2a/flow</code></td>\n<td>A2A-Nachrichtenfluss</td>\n</tr>\n<tr>\n<td><code>GET /stats/cron</code></td>\n<td>Cron-Analytics</td>\n</tr>\n<tr>\n<td><code>GET /stats/team</code> · <code>/stats/backlog</code> · <code>/stats/activity</code> · <code>/stats/summary</code> · <code>/stats/fleet</code> · <code>/stats/monitoring</code></td>\n<td>Dashboard-Aggregate</td>\n</tr>\n</tbody></table>\n<h2>GET /export/kpis</h2>\n<p>Tidy-Long-Export der Betriebs-KPIs (Task 7418541b). Daten-SSOT ist\n<code>src/db/stats.ts</code> — die Export-Ebene flacht nur ab, sie misst nichts selbst.</p>\n<pre><code class=\"hljs language-plaintext\">GET /export/kpis?format=csv|json|xlsx&amp;days=7</code></pre><table>\n<thead>\n<tr>\n<th>Parameter</th>\n<th>Werte</th>\n<th>Standard</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>format</code></td>\n<td><code>csv</code> · <code>json</code> · <code>xlsx</code></td>\n<td><code>json</code></td>\n</tr>\n<tr>\n<td><code>days</code></td>\n<td><code>1</code>–<code>365</code> (Zeitfenster für Agent-Overview)</td>\n<td><code>7</code></td>\n</tr>\n</tbody></table>\n<p>Antwort:</p>\n<ul>\n<li><code>format=json</code> → <code>{ generated_at, period_days, format: &quot;long&quot;, columns, row_count, rows[] }</code></li>\n<li><code>format=csv</code> → <code>text/csv; charset=utf-8</code> (RFC 4180, BOM, CRLF) als Anhang</li>\n<li><code>format=xlsx</code> → Excel-Arbeitsmappe (ein Sheet <code>KPIs</code>) als Anhang</li>\n</ul>\n<p>Tidy-Long-Spalten (in allen Formaten identisch):</p>\n<table>\n<thead>\n<tr>\n<th>Spalte</th>\n<th>Bedeutung</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>kategorie</code></td>\n<td>KPI-Gruppe: <code>fleet</code>, <code>summary</code>, <code>backlog</code>, <code>activity</code>, <code>team</code>, <code>monitoring</code>, <code>agent_overview</code></td>\n</tr>\n<tr>\n<td><code>metrik</code></td>\n<td>Geflachteter Metrik-Pfad (z. B. <code>throughput.done_24h_total</code>)</td>\n</tr>\n<tr>\n<td><code>wert</code></td>\n<td>Skalarer Wert (Zahl, Text oder <code>NULL</code>, wenn nur <code>detail</code> Daten trägt)</td>\n</tr>\n<tr>\n<td><code>einheit</code></td>\n<td><code>value</code> · <code>count</code> · <code>text</code> · <code>json</code></td>\n</tr>\n<tr>\n<td><code>zeitstempel</code></td>\n<td>ISO-8601-Erzeugungszeitstempel des Exports</td>\n</tr>\n<tr>\n<td><code>quelle</code></td>\n<td>Quellfunktion in <code>src/db/stats.ts</code></td>\n</tr>\n<tr>\n<td><code>detail</code></td>\n<td>JSON-Payload für Arrays/tiefe Objekte, sonst leer</td>\n</tr>\n</tbody></table>\n<p>Beispiel:</p>\n<pre><code class=\"hljs language-bash\">curl -s -H <span class=\"hljs-string\">&quot;Authorization: Bearer <span class=\"hljs-variable\">$MIND_KEY</span>&quot;</span> \\\n  <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone/export/kpis?format=csv&amp;days=7&quot;</span> -o kpis.csv</code></pre><p>Die WebUI-Seite <code>/stats</code> rendert denselben Export als drei Download-Buttons\n(CSV/JSON/XLSX) in der Sektion „KPI-Export“.</p>\n","urls":{"html":"/docs/api/stats","text":"/docs/api/stats?format=text","json":"/docs/api/stats?format=json","llm":"/docs/api/stats?format=llm"},"translations_available":["en","de"],"wordCount":260,"readMinutes":1,"requestedLang":"de","contentMarkdown":"\n# Stats & KPI API\n\nSynapse stellt schreibgeschützte Statistiken zu Agenten-Gesundheit, API-Nutzung,\nTrends und Fleet-KPIs bereit. Alle Endpoints akzeptieren entweder einen MindKey\n(`Authorization: Bearer`) oder ein User-JWT (`requireMindOrUser`).\n\nBestehende Analytics-Routen (siehe auch die `/stats`-Seite im WebUI):\n\n| Route | Zweck |\n| --- | --- |\n| `GET /stats/agent` | Übersicht aller Agenten (Zeitfenster: `days`) |\n| `GET /stats/agent/comparison` | Agenten-Vergleich |\n| `GET /stats/agent/:mindName` | Detailstatistik je Agent |\n| `GET /stats/agent/:mindName/health` | Health-Score |\n| `GET /stats/agent/:mindName/heatmap` | Aktivitäts-Heatmap |\n| `GET /stats/agent/:mindName/sessions` | Session-Tracker |\n| `GET /stats/api` | API-Nutzung (global) |\n| `GET /stats/trends` | Zeitreihen |\n| `GET /stats/chat/response-times` | Chat-Antwortzeiten |\n| `GET /stats/a2a/flow` | A2A-Nachrichtenfluss |\n| `GET /stats/cron` | Cron-Analytics |\n| `GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring` | Dashboard-Aggregate |\n\n## GET /export/kpis\n\nTidy-Long-Export der Betriebs-KPIs (Task 7418541b). Daten-SSOT ist\n`src/db/stats.ts` — die Export-Ebene flacht nur ab, sie misst nichts selbst.\n\n```\nGET /export/kpis?format=csv|json|xlsx&days=7\n```\n\n| Parameter | Werte | Standard |\n| --- | --- | --- |\n| `format` | `csv` · `json` · `xlsx` | `json` |\n| `days` | `1`–`365` (Zeitfenster für Agent-Overview) | `7` |\n\nAntwort:\n\n- `format=json` → `{ generated_at, period_days, format: \"long\", columns, row_count, rows[] }`\n- `format=csv` → `text/csv; charset=utf-8` (RFC 4180, BOM, CRLF) als Anhang\n- `format=xlsx` → Excel-Arbeitsmappe (ein Sheet `KPIs`) als Anhang\n\nTidy-Long-Spalten (in allen Formaten identisch):\n\n| Spalte | Bedeutung |\n| --- | --- |\n| `kategorie` | KPI-Gruppe: `fleet`, `summary`, `backlog`, `activity`, `team`, `monitoring`, `agent_overview` |\n| `metrik` | Geflachteter Metrik-Pfad (z. B. `throughput.done_24h_total`) |\n| `wert` | Skalarer Wert (Zahl, Text oder `NULL`, wenn nur `detail` Daten trägt) |\n| `einheit` | `value` · `count` · `text` · `json` |\n| `zeitstempel` | ISO-8601-Erzeugungszeitstempel des Exports |\n| `quelle` | Quellfunktion in `src/db/stats.ts` |\n| `detail` | JSON-Payload für Arrays/tiefe Objekte, sonst leer |\n\nBeispiel:\n\n```bash\ncurl -s -H \"Authorization: Bearer $MIND_KEY\" \\\n  \"https://synapse.schaefer.zone/export/kpis?format=csv&days=7\" -o kpis.csv\n```\n\nDie WebUI-Seite `/stats` rendert denselben Export als drei Download-Buttons\n(CSV/JSON/XLSX) in der Sektion „KPI-Export“.\n","contentHtml":"<h1>Stats &amp; KPI API</h1>\n<p>Synapse stellt schreibgeschützte Statistiken zu Agenten-Gesundheit, API-Nutzung,\nTrends und Fleet-KPIs bereit. Alle Endpoints akzeptieren entweder einen MindKey\n(<code>Authorization: Bearer</code>) oder ein User-JWT (<code>requireMindOrUser</code>).</p>\n<p>Bestehende Analytics-Routen (siehe auch die <code>/stats</code>-Seite im WebUI):</p>\n<table>\n<thead>\n<tr>\n<th>Route</th>\n<th>Zweck</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>GET /stats/agent</code></td>\n<td>Übersicht aller Agenten (Zeitfenster: <code>days</code>)</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/comparison</code></td>\n<td>Agenten-Vergleich</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName</code></td>\n<td>Detailstatistik je Agent</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName/health</code></td>\n<td>Health-Score</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName/heatmap</code></td>\n<td>Aktivitäts-Heatmap</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName/sessions</code></td>\n<td>Session-Tracker</td>\n</tr>\n<tr>\n<td><code>GET /stats/api</code></td>\n<td>API-Nutzung (global)</td>\n</tr>\n<tr>\n<td><code>GET /stats/trends</code></td>\n<td>Zeitreihen</td>\n</tr>\n<tr>\n<td><code>GET /stats/chat/response-times</code></td>\n<td>Chat-Antwortzeiten</td>\n</tr>\n<tr>\n<td><code>GET /stats/a2a/flow</code></td>\n<td>A2A-Nachrichtenfluss</td>\n</tr>\n<tr>\n<td><code>GET /stats/cron</code></td>\n<td>Cron-Analytics</td>\n</tr>\n<tr>\n<td><code>GET /stats/team</code> · <code>/stats/backlog</code> · <code>/stats/activity</code> · <code>/stats/summary</code> · <code>/stats/fleet</code> · <code>/stats/monitoring</code></td>\n<td>Dashboard-Aggregate</td>\n</tr>\n</tbody></table>\n<h2>GET /export/kpis</h2>\n<p>Tidy-Long-Export der Betriebs-KPIs (Task 7418541b). Daten-SSOT ist\n<code>src/db/stats.ts</code> — die Export-Ebene flacht nur ab, sie misst nichts selbst.</p>\n<pre><code class=\"hljs language-plaintext\">GET /export/kpis?format=csv|json|xlsx&amp;days=7</code></pre><table>\n<thead>\n<tr>\n<th>Parameter</th>\n<th>Werte</th>\n<th>Standard</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>format</code></td>\n<td><code>csv</code> · <code>json</code> · <code>xlsx</code></td>\n<td><code>json</code></td>\n</tr>\n<tr>\n<td><code>days</code></td>\n<td><code>1</code>–<code>365</code> (Zeitfenster für Agent-Overview)</td>\n<td><code>7</code></td>\n</tr>\n</tbody></table>\n<p>Antwort:</p>\n<ul>\n<li><code>format=json</code> → <code>{ generated_at, period_days, format: &quot;long&quot;, columns, row_count, rows[] }</code></li>\n<li><code>format=csv</code> → <code>text/csv; charset=utf-8</code> (RFC 4180, BOM, CRLF) als Anhang</li>\n<li><code>format=xlsx</code> → Excel-Arbeitsmappe (ein Sheet <code>KPIs</code>) als Anhang</li>\n</ul>\n<p>Tidy-Long-Spalten (in allen Formaten identisch):</p>\n<table>\n<thead>\n<tr>\n<th>Spalte</th>\n<th>Bedeutung</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>kategorie</code></td>\n<td>KPI-Gruppe: <code>fleet</code>, <code>summary</code>, <code>backlog</code>, <code>activity</code>, <code>team</code>, <code>monitoring</code>, <code>agent_overview</code></td>\n</tr>\n<tr>\n<td><code>metrik</code></td>\n<td>Geflachteter Metrik-Pfad (z. B. <code>throughput.done_24h_total</code>)</td>\n</tr>\n<tr>\n<td><code>wert</code></td>\n<td>Skalarer Wert (Zahl, Text oder <code>NULL</code>, wenn nur <code>detail</code> Daten trägt)</td>\n</tr>\n<tr>\n<td><code>einheit</code></td>\n<td><code>value</code> · <code>count</code> · <code>text</code> · <code>json</code></td>\n</tr>\n<tr>\n<td><code>zeitstempel</code></td>\n<td>ISO-8601-Erzeugungszeitstempel des Exports</td>\n</tr>\n<tr>\n<td><code>quelle</code></td>\n<td>Quellfunktion in <code>src/db/stats.ts</code></td>\n</tr>\n<tr>\n<td><code>detail</code></td>\n<td>JSON-Payload für Arrays/tiefe Objekte, sonst leer</td>\n</tr>\n</tbody></table>\n<p>Beispiel:</p>\n<pre><code class=\"hljs language-bash\">curl -s -H <span class=\"hljs-string\">&quot;Authorization: Bearer <span class=\"hljs-variable\">$MIND_KEY</span>&quot;</span> \\\n  <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone/export/kpis?format=csv&amp;days=7&quot;</span> -o kpis.csv</code></pre><p>Die WebUI-Seite <code>/stats</code> rendert denselben Export als drei Download-Buttons\n(CSV/JSON/XLSX) in der Sektion „KPI-Export“.</p>\n","translationsAvailable":["en","de"]}