Instance health

Health checks tell you whether an agent or team can currently answer requests, without running it. Use them in your monitoring, after changing a deployment, or before routing users to an agent.

What is checked

Check	Fails when
Instance ID	The ID does not have the format `{deployment_id}.{component_type}.{component_id}` (`400`)
Deployment and component	The deployment or one of the components it references does not exist (`404`)
Configuration	The agent or team and all components it references can be loaded (`404` if not)
`llm_proxy_reachable`	A language model that the agent, or any agent of the team, needs is not available

Configuration errors are returned as HTTP errors. Problems with dependencies are returned with status 200 and "status": "UNHEALTHY".

Request

GET ${RUNTIME_BASE_URL}/v1/instances/{instance_id}/health
Authorization: Bearer ${ACCESS_TOKEN}
X-Tenant-ID: ${TENANT_ID}

The caller needs the service-monitoring role. Use a dedicated technical user for your monitoring system. See Roles and permissions.

Response

{
  "instance_id": "support-prod.agent.support-agent",
  "status": "HEALTHY",
  "checks": [
    { "check": "llm_proxy_reachable", "status": "HEALTHY", "message": "All 1 required model(s) healthy" }
  ]
}

status is HEALTHY only if all checks pass. Otherwise it is UNHEALTHY.
Each entry in checks has its own status and a message that explains a failure.
For teams, the models of all participating agents are checked.

Status codes

Status	Meaning
`200`	Check completed. Inspect `status`, it can be `UNHEALTHY`.
`400`	The instance ID is invalid or the component type is not supported
`401`	Not authenticated
`403`	The caller does not have the `service-monitoring` role
`404`	The deployment or a component does not exist

Best practices

Monitor the agents your users depend on, not all agents in the tenant.
Poll at a moderate interval, for example every one to five minutes. Results are cached for a few seconds, so more frequent calls give no extra information.
Alert on repeated failures, not on a single UNHEALTHY result. Short interruptions of a model can resolve themselves.
Treat 404 as a configuration problem. It usually means a deployment or component was deleted or renamed.
Check after every deployment change. Call the endpoint for each published instance after updating a deployment.
Combine with real requests. A healthy instance can still give poor answers. For quality, run a few typical questions regularly and review feedback.