Aggregate agent connection counters

Returns tenant-scoped aggregates of connection state for the Agents dashboard summary cards. The response groups the agent_instances rows by deployment_mode, connection_status, and transport.

The underlying query hits the (tenant_id, connection_status) index added in migration 074, so response time is independent of fleet size for a single tenant.

Scope rules:

Non-super callers: always scoped to the caller’s tenant; body.tenant_id is silently ignored.
Super-admins: pass tenant_id to scope to a single tenant, or omit it to aggregate globally across all tenants.
agent_type (optional, both roles) narrows to a single fleet.

POST

agents

get_connection_stats

Aggregate agent connection counters

curl --request POST \
  --url https://api.svantic.com/agents/get_connection_stats \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_type": "orchestrator"
}
'

{
  "ok": true,
  "stats": {
    "total": 14,
    "by_deployment_mode": {
      "hosted": 8,
      "connected": 6
    },
    "by_status": {
      "online": 5,
      "healthy": 7,
      "degraded": 1,
      "offline": 1
    },
    "by_transport": {
      "ws": 5,
      "callback": 7,
      "unknown": 2
    }
  },
  "tenant_id": "tenant-acme",
  "agent_type": "orchestrator"
}

Body

application/json

Scope filters for POST /agents/get_connection_stats. Both fields are optional. With none set, stats cover the caller's entire tenant.

agent_type

string

Restrict the aggregate to a single agent-type fleet.

tenant_id

string

Super-admin-only override (same semantics as get_connection). Ignored for non-super callers. When a super-admin omits this, stats are aggregated globally across all tenants.

Response

Aggregated connection counters for the scope.

boolean

required

stats

object

required

Show child attributes

tenant_id

string | null

Echoed scope. Non-null for tenant-scoped queries (the default for non-super callers); null only when a super-admin aggregates globally.

agent_type

string

Echoed when the request included an agent_type filter.

Get agent connection state

Allow Agent Type

Aggregate agent connection counters

curl --request POST \
  --url https://api.svantic.com/agents/get_connection_stats \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_type": "orchestrator"
}
'

{
  "ok": true,
  "stats": {
    "total": 14,
    "by_deployment_mode": {
      "hosted": 8,
      "connected": 6
    },
    "by_status": {
      "online": 5,
      "healthy": 7,
      "degraded": 1,
      "offline": 1
    },
    "by_transport": {
      "ws": 5,
      "callback": 7,
      "unknown": 2
    }
  },
  "tenant_id": "tenant-acme",
  "agent_type": "orchestrator"
}