Get agent connection state

Returns unified live connection state for a single agent instance. The response shape is identical for hosted (HTTP callback) and connected (WebSocket) deployments; switch on the transport and connection_status fields to render.

Data is sourced from the gateway’s agent_instances row, which the mesh keeps up to date via the internal /internal/agents/record_* write path on every dispatch and WS lifecycle event. That row is the single source of truth — there is no need to cross-reference the mesh /metrics endpoint except for aggregate fleet telemetry.

Non-super callers can only query instances in their own tenant; super-admins may pass tenant_id in the body to narrow the lookup, or omit it for a global search by instance_id.

POST

agents

get_connection

Get agent connection state

curl --request POST \
  --url https://api.svantic.com/agents/get_connection \
  --header 'Content-Type: application/json' \
  --data '
{
  "instance_id": "inst-orchestrator-7f3d"
}
'

{
  "ok": true,
  "connection": {
    "instance_id": "inst-orchestrator-7f3d",
    "agent_type": "orchestrator",
    "tenant_id": "tenant-acme",
    "deployment_mode": "hosted",
    "transport": "callback",
    "connection_status": "healthy",
    "owner_pod": null,
    "connected_since": null,
    "last_dispatch_at": "2026-04-17T12:00:05.000Z",
    "dispatches_succeeded": 142,
    "dispatches_failed": 3,
    "last_dispatch_error": null,
    "status": "available",
    "last_seen": "2026-04-17T12:00:05.000Z",
    "ws_mesh_pod_id": null,
    "ws_last_seen": null
  }
}

Body

application/json

instance_id

string

required

Agent instance identifier.

tenant_id

string

Super-admin-only override. Ignored for non-super callers, whose tenant is always read from the auth context. When a super-admin omits this, the lookup is global by instance_id.

Response

Connection state for the instance.

boolean

required

connection

object

required

Unified connection-state envelope for a single agent instance. Shape is identical regardless of deployment_mode: hosted agents report transport=callback, connected agents report transport=ws. The dashboard renders the same card for either, switching only on the transport and connection_status fields. Maintained by the mesh write path (/internal/agents/record_*) against the agent_instances row. The gateway row is the single source of truth — clients should not cross-reference the mesh /metrics endpoint except for aggregate fleet-wide telemetry.

Show child attributes

Get agent instance detail

Aggregate agent connection counters

Get agent connection state

curl --request POST \
  --url https://api.svantic.com/agents/get_connection \
  --header 'Content-Type: application/json' \
  --data '
{
  "instance_id": "inst-orchestrator-7f3d"
}
'

{
  "ok": true,
  "connection": {
    "instance_id": "inst-orchestrator-7f3d",
    "agent_type": "orchestrator",
    "tenant_id": "tenant-acme",
    "deployment_mode": "hosted",
    "transport": "callback",
    "connection_status": "healthy",
    "owner_pod": null,
    "connected_since": null,
    "last_dispatch_at": "2026-04-17T12:00:05.000Z",
    "dispatches_succeeded": 142,
    "dispatches_failed": 3,
    "last_dispatch_error": null,
    "status": "available",
    "last_seen": "2026-04-17T12:00:05.000Z",
    "ws_mesh_pod_id": null,
    "ws_last_seen": null
  }
}