{"title":"통계 & KPI API","slug":"stats","category":"api","summary":"통계 엔드포인트, 플릿 KPI, LLM 에이전트를 위한 tidy-long KPI 내보내기(CSV/JSON/XLSX).","audience":["human"],"tags":[],"word_count":265,"read_minutes":1,"lang":"ko","translated":true,"requested_lang":"ko","content_markdown":"\n# 통계 & KPI API\n\nSynapse는 에이전트 건강, API 사용량, 추세, 플릿 KPI에 대한 읽기 전용 통계를 노출합니다. 모든 엔드포인트는 MindKey(`Authorization: Bearer`) 또는 사용자 JWT(`requireMindOrUser`)를 받습니다.\n\n기존 분석 라우트(WebUI의 `/stats` 페이지 참조):\n\n| 라우트 | 목적 |\n| --- | --- |\n| `GET /stats/agent` | 모든 에이전트 개요(기간: `days`) |\n| `GET /stats/agent/comparison` | 에이전트 간 비교 |\n| `GET /stats/agent/:mindName` | 한 에이전트의 상세 통계 |\n| `GET /stats/agent/:mindName/health` | 건강 점수 |\n| `GET /stats/agent/:mindName/heatmap` | 활동 히트맵 |\n| `GET /stats/agent/:mindName/sessions` | 세션 트래커 |\n| `GET /stats/api` | API 사용량(전역) |\n| `GET /stats/trends` | 시계열 |\n| `GET /stats/chat/response-times` | 채팅 응답 시간 |\n| `GET /stats/a2a/flow` | A2A 메시지 흐름 |\n| `GET /stats/cron` | 크론 분석 |\n| `GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring` | 대시보드 집계 |\n\n## GET /export/kpis\n\n운영 KPI의 tidy-long 내보내기(task 7418541b). 데이터의 진실 원천은 `src/db/stats.ts`입니다 — 내보내기 계층은 평탄화만 하며, 스스로는 아무것도 측정하지 않습니다.\n\n```\nGET /export/kpis?format=csv|json|xlsx&days=7\n```\n\n| 매개변수 | 값 | 기본값 |\n| --- | --- | --- |\n| `format` | `csv` · `json` · `xlsx` | `json` |\n| `days` | `1`–`365`(에이전트 개요의 창) | `7` |\n\n응답:\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) 첨부파일로\n- `format=xlsx` → Excel 통합문서(단일 시트 `KPIs`) 첨부파일로\n\ntidy-long 열(모든 형식에서 동일):\n\n| 열 | 의미 |\n| --- | --- |\n| `kategorie` | KPI 그룹: `fleet`, `summary`, `backlog`, `activity`, `team`, `monitoring`, `agent_overview` |\n| `metrik` | 평탄화된 메트릭 경로(예: `throughput.done_24h_total`) |\n| `wert` | 스칼라 값(숫자, 텍스트 또는 `detail`만 데이터를 담을 때 `NULL`) |\n| `einheit` | `value` · `count` · `text` · `json` |\n| `zeitstempel` | 내보내기 생성의 ISO-8601 타임스탬프 |\n| `quelle` | `src/db/stats.ts`의 원천 함수 |\n| `detail` | 배열/깊은 객체용 JSON 페이로드, 그 외에는 비어 있음 |\n\n예시:\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\nWebUI의 `/stats` 페이지는 같은 내보내기를 「KPI export」 섹션에 세 개의 다운로드 버튼(CSV/JSON/XLSX)으로 렌더링합니다.\n","content_html":"<h1>통계 &amp; KPI API</h1>\n<p>Synapse는 에이전트 건강, API 사용량, 추세, 플릿 KPI에 대한 읽기 전용 통계를 노출합니다. 모든 엔드포인트는 MindKey(<code>Authorization: Bearer</code>) 또는 사용자 JWT(<code>requireMindOrUser</code>)를 받습니다.</p>\n<p>기존 분석 라우트(WebUI의 <code>/stats</code> 페이지 참조):</p>\n<table>\n<thead>\n<tr>\n<th>라우트</th>\n<th>목적</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>GET /stats/agent</code></td>\n<td>모든 에이전트 개요(기간: <code>days</code>)</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/comparison</code></td>\n<td>에이전트 간 비교</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName</code></td>\n<td>한 에이전트의 상세 통계</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName/health</code></td>\n<td>건강 점수</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName/heatmap</code></td>\n<td>활동 히트맵</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName/sessions</code></td>\n<td>세션 트래커</td>\n</tr>\n<tr>\n<td><code>GET /stats/api</code></td>\n<td>API 사용량(전역)</td>\n</tr>\n<tr>\n<td><code>GET /stats/trends</code></td>\n<td>시계열</td>\n</tr>\n<tr>\n<td><code>GET /stats/chat/response-times</code></td>\n<td>채팅 응답 시간</td>\n</tr>\n<tr>\n<td><code>GET /stats/a2a/flow</code></td>\n<td>A2A 메시지 흐름</td>\n</tr>\n<tr>\n<td><code>GET /stats/cron</code></td>\n<td>크론 분석</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>대시보드 집계</td>\n</tr>\n</tbody></table>\n<h2>GET /export/kpis</h2>\n<p>운영 KPI의 tidy-long 내보내기(task 7418541b). 데이터의 진실 원천은 <code>src/db/stats.ts</code>입니다 — 내보내기 계층은 평탄화만 하며, 스스로는 아무것도 측정하지 않습니다.</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>매개변수</th>\n<th>값</th>\n<th>기본값</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>(에이전트 개요의 창)</td>\n<td><code>7</code></td>\n</tr>\n</tbody></table>\n<p>응답:</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) 첨부파일로</li>\n<li><code>format=xlsx</code> → Excel 통합문서(단일 시트 <code>KPIs</code>) 첨부파일로</li>\n</ul>\n<p>tidy-long 열(모든 형식에서 동일):</p>\n<table>\n<thead>\n<tr>\n<th>열</th>\n<th>의미</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>kategorie</code></td>\n<td>KPI 그룹: <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>평탄화된 메트릭 경로(예: <code>throughput.done_24h_total</code>)</td>\n</tr>\n<tr>\n<td><code>wert</code></td>\n<td>스칼라 값(숫자, 텍스트 또는 <code>detail</code>만 데이터를 담을 때 <code>NULL</code>)</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 타임스탬프</td>\n</tr>\n<tr>\n<td><code>quelle</code></td>\n<td><code>src/db/stats.ts</code>의 원천 함수</td>\n</tr>\n<tr>\n<td><code>detail</code></td>\n<td>배열/깊은 객체용 JSON 페이로드, 그 외에는 비어 있음</td>\n</tr>\n</tbody></table>\n<p>예시:</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>WebUI의 <code>/stats</code> 페이지는 같은 내보내기를 「KPI export」 섹션에 세 개의 다운로드 버튼(CSV/JSON/XLSX)으로 렌더링합니다.</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","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"],"wordCount":265,"readMinutes":1,"requestedLang":"ko","contentMarkdown":"\n# 통계 & KPI API\n\nSynapse는 에이전트 건강, API 사용량, 추세, 플릿 KPI에 대한 읽기 전용 통계를 노출합니다. 모든 엔드포인트는 MindKey(`Authorization: Bearer`) 또는 사용자 JWT(`requireMindOrUser`)를 받습니다.\n\n기존 분석 라우트(WebUI의 `/stats` 페이지 참조):\n\n| 라우트 | 목적 |\n| --- | --- |\n| `GET /stats/agent` | 모든 에이전트 개요(기간: `days`) |\n| `GET /stats/agent/comparison` | 에이전트 간 비교 |\n| `GET /stats/agent/:mindName` | 한 에이전트의 상세 통계 |\n| `GET /stats/agent/:mindName/health` | 건강 점수 |\n| `GET /stats/agent/:mindName/heatmap` | 활동 히트맵 |\n| `GET /stats/agent/:mindName/sessions` | 세션 트래커 |\n| `GET /stats/api` | API 사용량(전역) |\n| `GET /stats/trends` | 시계열 |\n| `GET /stats/chat/response-times` | 채팅 응답 시간 |\n| `GET /stats/a2a/flow` | A2A 메시지 흐름 |\n| `GET /stats/cron` | 크론 분석 |\n| `GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring` | 대시보드 집계 |\n\n## GET /export/kpis\n\n운영 KPI의 tidy-long 내보내기(task 7418541b). 데이터의 진실 원천은 `src/db/stats.ts`입니다 — 내보내기 계층은 평탄화만 하며, 스스로는 아무것도 측정하지 않습니다.\n\n```\nGET /export/kpis?format=csv|json|xlsx&days=7\n```\n\n| 매개변수 | 값 | 기본값 |\n| --- | --- | --- |\n| `format` | `csv` · `json` · `xlsx` | `json` |\n| `days` | `1`–`365`(에이전트 개요의 창) | `7` |\n\n응답:\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) 첨부파일로\n- `format=xlsx` → Excel 통합문서(단일 시트 `KPIs`) 첨부파일로\n\ntidy-long 열(모든 형식에서 동일):\n\n| 열 | 의미 |\n| --- | --- |\n| `kategorie` | KPI 그룹: `fleet`, `summary`, `backlog`, `activity`, `team`, `monitoring`, `agent_overview` |\n| `metrik` | 평탄화된 메트릭 경로(예: `throughput.done_24h_total`) |\n| `wert` | 스칼라 값(숫자, 텍스트 또는 `detail`만 데이터를 담을 때 `NULL`) |\n| `einheit` | `value` · `count` · `text` · `json` |\n| `zeitstempel` | 내보내기 생성의 ISO-8601 타임스탬프 |\n| `quelle` | `src/db/stats.ts`의 원천 함수 |\n| `detail` | 배열/깊은 객체용 JSON 페이로드, 그 외에는 비어 있음 |\n\n예시:\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\nWebUI의 `/stats` 페이지는 같은 내보내기를 「KPI export」 섹션에 세 개의 다운로드 버튼(CSV/JSON/XLSX)으로 렌더링합니다.\n","contentHtml":"<h1>통계 &amp; KPI API</h1>\n<p>Synapse는 에이전트 건강, API 사용량, 추세, 플릿 KPI에 대한 읽기 전용 통계를 노출합니다. 모든 엔드포인트는 MindKey(<code>Authorization: Bearer</code>) 또는 사용자 JWT(<code>requireMindOrUser</code>)를 받습니다.</p>\n<p>기존 분석 라우트(WebUI의 <code>/stats</code> 페이지 참조):</p>\n<table>\n<thead>\n<tr>\n<th>라우트</th>\n<th>목적</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>GET /stats/agent</code></td>\n<td>모든 에이전트 개요(기간: <code>days</code>)</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/comparison</code></td>\n<td>에이전트 간 비교</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName</code></td>\n<td>한 에이전트의 상세 통계</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName/health</code></td>\n<td>건강 점수</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName/heatmap</code></td>\n<td>활동 히트맵</td>\n</tr>\n<tr>\n<td><code>GET /stats/agent/:mindName/sessions</code></td>\n<td>세션 트래커</td>\n</tr>\n<tr>\n<td><code>GET /stats/api</code></td>\n<td>API 사용량(전역)</td>\n</tr>\n<tr>\n<td><code>GET /stats/trends</code></td>\n<td>시계열</td>\n</tr>\n<tr>\n<td><code>GET /stats/chat/response-times</code></td>\n<td>채팅 응답 시간</td>\n</tr>\n<tr>\n<td><code>GET /stats/a2a/flow</code></td>\n<td>A2A 메시지 흐름</td>\n</tr>\n<tr>\n<td><code>GET /stats/cron</code></td>\n<td>크론 분석</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>대시보드 집계</td>\n</tr>\n</tbody></table>\n<h2>GET /export/kpis</h2>\n<p>운영 KPI의 tidy-long 내보내기(task 7418541b). 데이터의 진실 원천은 <code>src/db/stats.ts</code>입니다 — 내보내기 계층은 평탄화만 하며, 스스로는 아무것도 측정하지 않습니다.</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>매개변수</th>\n<th>값</th>\n<th>기본값</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>(에이전트 개요의 창)</td>\n<td><code>7</code></td>\n</tr>\n</tbody></table>\n<p>응답:</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) 첨부파일로</li>\n<li><code>format=xlsx</code> → Excel 통합문서(단일 시트 <code>KPIs</code>) 첨부파일로</li>\n</ul>\n<p>tidy-long 열(모든 형식에서 동일):</p>\n<table>\n<thead>\n<tr>\n<th>열</th>\n<th>의미</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>kategorie</code></td>\n<td>KPI 그룹: <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>평탄화된 메트릭 경로(예: <code>throughput.done_24h_total</code>)</td>\n</tr>\n<tr>\n<td><code>wert</code></td>\n<td>스칼라 값(숫자, 텍스트 또는 <code>detail</code>만 데이터를 담을 때 <code>NULL</code>)</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 타임스탬프</td>\n</tr>\n<tr>\n<td><code>quelle</code></td>\n<td><code>src/db/stats.ts</code>의 원천 함수</td>\n</tr>\n<tr>\n<td><code>detail</code></td>\n<td>배열/깊은 객체용 JSON 페이로드, 그 외에는 비어 있음</td>\n</tr>\n</tbody></table>\n<p>예시:</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>WebUI의 <code>/stats</code> 페이지는 같은 내보내기를 「KPI export」 섹션에 세 개의 다운로드 버튼(CSV/JSON/XLSX)으로 렌더링합니다.</p>\n","translationsAvailable":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}