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"
}
'

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({instance_id: 'inst-orchestrator-7f3d'})
};

fetch('https://api.svantic.com/agents/get_connection', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.svantic.com/agents/get_connection"

payload = { "instance_id": "inst-orchestrator-7f3d" }
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.svantic.com/agents/get_connection"

	payload := strings.NewReader("{\n  \"instance_id\": \"inst-orchestrator-7f3d\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "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 connection state

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

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({instance_id: 'inst-orchestrator-7f3d'})
};

fetch('https://api.svantic.com/agents/get_connection', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.svantic.com/agents/get_connection"

payload = { "instance_id": "inst-orchestrator-7f3d" }
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.svantic.com/agents/get_connection"

	payload := strings.NewReader("{\n  \"instance_id\": \"inst-orchestrator-7f3d\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "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
  }
}