Health API
Agent health scoring endpoints. Compute health scores across 5 dimensions, retrieve overview data for all agents, and access historical snapshots.
GET /api/agents/:id/health
Compute the health score for a single agent.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id | string | Agent ID |
Query Parameters
| Parameter | Type | Default | Range | Description |
|---|---|---|---|---|
window | number | 7 | 1–90 | Rolling window in days |
Response (200)
json
{
"agentId": "my-agent",
"overallScore": 82,
"trend": "improving",
"trendDelta": 5.3,
"dimensions": [
{
"name": "error_rate",
"score": 90,
"weight": 0.30,
"rawValue": 0.05,
"description": "5% error rate across 40 sessions"
},
{
"name": "cost_efficiency",
"score": 75,
"weight": 0.20,
"rawValue": 0.034,
"description": "Average cost $0.034 per session"
},
{
"name": "tool_success",
"score": 88,
"weight": 0.20,
"rawValue": 0.88,
"description": "88% tool call success rate"
},
{
"name": "latency",
"score": 72,
"weight": 0.15,
"rawValue": 2300,
"description": "Average latency 2300ms"
},
{
"name": "completion_rate",
"score": 85,
"weight": 0.15,
"rawValue": 0.85,
"description": "85% session completion rate"
}
],
"window": {
"from": "2026-02-01T00:00:00.000Z",
"to": "2026-02-08T00:00:00.000Z"
},
"sessionCount": 40,
"computedAt": "2026-02-08T10:30:00.000Z"
}Response Fields
| Field | Type | Description |
|---|---|---|
agentId | string | The agent ID |
overallScore | number | Weighted health score (0–100) |
trend | string | improving, stable, or degrading |
trendDelta | number | Point change from previous window |
dimensions | array | Per-dimension scores |
dimensions[].name | string | Dimension name |
dimensions[].score | number | Score (0–100) |
dimensions[].weight | number | Weight (0–1) |
dimensions[].rawValue | number | Raw metric value |
dimensions[].description | string | Human-readable description |
window | object | Time range used for computation |
sessionCount | number | Sessions in the window |
computedAt | string | ISO 8601 timestamp |
Errors
| Status | Condition |
|---|---|
| 400 | Invalid window parameter |
| 404 | No sessions found for agent in window |
GET /api/health/overview
Health overview for all agents.
Query Parameters
| Parameter | Type | Default | Range | Description |
|---|---|---|---|---|
window | number | 7 | 1–90 | Rolling window in days |
Response (200)
json
{
"agents": [
{
"agentId": "agent-a",
"overallScore": 82,
"trend": "improving",
"trendDelta": 5.3,
"dimensions": [ "..." ],
"window": { "from": "...", "to": "..." },
"sessionCount": 40,
"computedAt": "..."
},
{
"agentId": "agent-b",
"overallScore": 65,
"trend": "degrading",
"trendDelta": -8.1,
"dimensions": [ "..." ],
"window": { "from": "...", "to": "..." },
"sessionCount": 12,
"computedAt": "..."
}
],
"computedAt": "2026-02-08T10:30:00.000Z"
}GET /api/health/history
Historical health snapshots for an agent. Snapshots are saved automatically the first time health is queried each day.
Query Parameters
| Parameter | Type | Default | Range | Description |
|---|---|---|---|---|
agentId | string | (required) | — | Agent ID |
days | number | 30 | 1–365 | How many days of history |
Response (200)
json
{
"snapshots": [
{
"agentId": "my-agent",
"date": "2026-02-07",
"overallScore": 80,
"errorRateScore": 88,
"costEfficiencyScore": 73,
"toolSuccessScore": 85,
"latencyScore": 70,
"completionRateScore": 82,
"sessionCount": 15
},
{
"agentId": "my-agent",
"date": "2026-02-06",
"overallScore": 77,
"errorRateScore": 85,
"costEfficiencyScore": 70,
"toolSuccessScore": 82,
"latencyScore": 68,
"completionRateScore": 80,
"sessionCount": 12
}
],
"agentId": "my-agent",
"days": 30
}Errors
| Status | Condition |
|---|---|
| 400 | Missing agentId or invalid days |
GET /api/config/health-weights
Returns the current health scoring weights.
Response (200)
json
{
"errorRate": 0.30,
"costEfficiency": 0.20,
"toolSuccess": 0.20,
"latency": 0.15,
"completionRate": 0.15
}PUT /api/config/health-weights
Update health scoring weights. Currently returns 501 — weight customization is planned for a future release.
Request Body
json
{
"errorRate": 0.25,
"costEfficiency": 0.25,
"toolSuccess": 0.20,
"latency": 0.15,
"completionRate": 0.15
}Response (501)
json
{
"error": "Weight customization coming in a future release",
"status": 501
}