# सांख्यिकी और KPI API

Synapse एजेंट स्वास्थ्य, API उपयोग, रुझान और फ्लीट KPI के बारे में केवल-पढ़ने योग्य आँकड़े उपलब्ध कराता है। सभी एंडपॉइंट या तो MindKey (`Authorization: Bearer`) या उपयोगकर्ता JWT (`requireMindOrUser`) स्वीकार करते हैं।

मौजूदा एनालिटिक्स रूट (WebUI में `/stats` पृष्ठ देखें):

| रूट | उद्देश्य |
| --- | --- |
| `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

परिचालन KPI का tidy-long निर्यात (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
```

WebUI का `/stats` पृष्ठ वही निर्यात «KPI export» अनुभाग में तीन डाउनलोड बटनों (CSV/JSON/XLSX) के रूप में प्रस्तुत करता है।