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

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

fetch('https://api.svantic.com/agents/get_connection_stats', 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_stats"

payload = { "agent_type": "orchestrator" }
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_stats"

	payload := strings.NewReader("{\n  \"agent_type\": \"orchestrator\"\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,
  "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"
}

{
  "error": "Invalid request body",
  "code": "BAD_REQUEST"
}

{
  "error": "Invalid or expired token",
  "code": "unauthorized"
}

{
  "error": "JWT does not include the required scope for this operation",
  "code": "forbidden"
}

{
  "error": "Internal server error",
  "code": "INTERNAL_ERROR",
  "request_id": "req_01EXAMPLE",
  "timestamp": "2026-03-31T12:00:00.000Z"
}

{
  "error": "Bad gateway",
  "code": "BAD_GATEWAY"
}

{
  "error": "Service temporarily unavailable",
  "code": "SERVICE_UNAVAILABLE"
}

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.

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

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

fetch('https://api.svantic.com/agents/get_connection_stats', 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_stats"

payload = { "agent_type": "orchestrator" }
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_stats"

	payload := strings.NewReader("{\n  \"agent_type\": \"orchestrator\"\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,
  "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"
}

{
  "error": "Invalid request body",
  "code": "BAD_REQUEST"
}

{
  "error": "Invalid or expired token",
  "code": "unauthorized"
}

{
  "error": "JWT does not include the required scope for this operation",
  "code": "forbidden"
}

{
  "error": "Internal server error",
  "code": "INTERNAL_ERROR",
  "request_id": "req_01EXAMPLE",
  "timestamp": "2026-03-31T12:00:00.000Z"
}

{
  "error": "Bad gateway",
  "code": "BAD_GATEWAY"
}

{
  "error": "Service temporarily unavailable",
  "code": "SERVICE_UNAVAILABLE"
}

REST API

WebSocket

Aggregate agent connection counters

Body

Response