Stats & KPI API

1 min · 297 words English

Statistics endpoints, fleet KPIs and tidy-long KPI export (CSV/JSON/XLSX) for LLM agents.

Read this article as: 📄 Plain Text ⚡ JSON 🤖 LLM Format

Language: English Deutsch

Stats & KPI API

Synapse exposes read-only statistics for agent health, API usage, trends and fleet KPIs. All endpoints accept either a MindKey (Authorization: Bearer) or a user JWT (requireMindOrUser).

Existing analytics routes (see the /stats page in the WebUI):

Route	Purpose
`GET /stats/agent`	All agents overview (period: `days`)
`GET /stats/agent/comparison`	Cross-agent comparison
`GET /stats/agent/:mindName`	Detailed stats for one agent
`GET /stats/agent/:mindName/health`	Health score
`GET /stats/agent/:mindName/heatmap`	Activity heatmap
`GET /stats/agent/:mindName/sessions`	Session tracker
`GET /stats/api`	API usage (global)
`GET /stats/trends`	Time series
`GET /stats/chat/response-times`	Chat response times
`GET /stats/a2a/flow`	A2A message flow
`GET /stats/cron`	Cron analytics
`GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring`	Dashboard aggregates

GET /export/kpis

Tidy-long export of the operational KPIs (task 7418541b). The data source of truth is src/db/stats.ts — the export layer only flattens, it measures nothing itself.

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

Parameter	Values	Default
`format`	`csv` · `json` · `xlsx`	`json`
`days`	`1`–`365` (window for agent overview)	`7`

Response:

format=json → { generated_at, period_days, format: "long", columns, row_count, rows[] }
format=csv → text/csv; charset=utf-8 (RFC 4180, BOM, CRLF) as attachment
format=xlsx → Excel workbook (single sheet KPIs) as attachment

Tidy-long columns (identical in all formats):

Column	Meaning
`kategorie`	KPI group: `fleet`, `summary`, `backlog`, `activity`, `team`, `monitoring`, `agent_overview`
`metrik`	Flattened metric path (e.g. `throughput.done_24h_total`)
`wert`	Scalar value (number, text or `NULL` when only `detail` carries data)
`einheit`	`value` · `count` · `text` · `json`
`zeitstempel`	ISO-8601 generation timestamp of the export
`quelle`	Source function in `src/db/stats.ts`
`detail`	JSON payload for arrays/deep objects, otherwise empty

Example:

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

The WebUI /stats page renders the same export as three download buttons (CSV/JSON/XLSX) in the "KPI export" section.