List All Agent Health Records — GET /v1/health/agents

Retrieve health metrics for all agents, including online status, latency, and success rate derived from actual invocation history.

Returns a health record for every known agent, updated continuously from invocation history. Use this endpoint to check liveness and performance before routing traffic.

Response

Returns { "items": [AgentHealthRecord] }.

items · array

Array of AgentHealthRecord objects, one per known agent.

Show AgentHealthRecord

agent_id · string · required

The unique identifier of the agent.

provider_id · string · required

The provider that owns this agent.

status · string · required

Current health status. One of unknown, online, degraded, or offline.

last_seen_at · string (ISO 8601)

UTC timestamp of the most recent successful invocation. Absent if the agent has never been successfully invoked.

last_latency_ms · integer

Round-trip latency in milliseconds for the most recent invocation. Absent if unavailable.

success_count · integer · required

Total number of successful invocations recorded for this agent.

failure_count · integer · required

Total number of failed invocations recorded for this agent.

success_rate · number (float) · required

Ratio of successful invocations to total invocations, in the range [0.0, 1.0].

updated_at · string (ISO 8601) · required

UTC timestamp when this health record was last updated.

Example

curl http://your-node:8042/v1/health/agents

Example response

{
  "items": [
    {
      "agent_id": "stripe-agent",
      "provider_id": "acme-labs",
      "status": "online",
      "last_seen_at": "2025-01-15T10:30:02Z",
      "last_latency_ms": 312,
      "success_count": 482,
      "failure_count": 3,
      "success_rate": 0.9938,
      "updated_at": "2025-01-15T10:30:02Z"
    },
    {
      "agent_id": "legacy-agent",
      "provider_id": "old-corp",
      "status": "offline",
      "last_seen_at": "2025-01-10T06:00:00Z",
      "success_count": 10,
      "failure_count": 45,
      "success_rate": 0.1818,
      "updated_at": "2025-01-10T06:00:00Z"
    }
  ]
}