Skip to main content

​
GET /api/overview

Returns a high-level summary of the entire fleet, including agent counts, threat statistics, and the active policy version. Designed for dashboard UIs and monitoring integrations. 
curl -X GET https://localhost:8443/api/overview \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "ok": true,
  "data": {
    "totalAgents": 12,
    "onlineAgents": 10,
    "staleAgents": 1,
    "offlineAgents": 1,
    "threatSummary": {
      "last24h": {
        "total": 47,
        "critical": 2,
        "high": 8,
        "medium": 15,
        "low": 22
      },
      "last7d": {
        "total": 234,
        "critical": 5,
        "high": 42,
        "medium": 89,
        "low": 98
      }
    },
    "activePolicyVersion": "v3",
    "topThreats": [
      { "type": "brute_force", "count": 52 },
      { "type": "port_scan", "count": 38 },
      { "type": "suspicious_process", "count": 21 }
    ],
    "agentsByOs": {
      "linux": 8,
      "darwin": 3,
      "win32": 1
    },
    "updatedAt": "2026-03-07T12:05:00.000Z"
  }
}

​
Response Fields

FieldTypeDescription
totalAgentsnumberTotal registered agents
onlineAgentsnumberAgents with a recent heartbeat
staleAgentsnumberAgents that missed their heartbeat window but are not yet offline
offlineAgentsnumberAgents that have been unreachable beyond the timeout
threatSummaryobjectThreat counts by severity for the last 24 hours and 7 days
activePolicyVersionstringCurrently active policy version (e.g., v3)
topThreatsarrayMost frequent threat types across the fleet
agentsByOsobjectAgent count grouped by operating system
updatedAtstringISO 8601 timestamp of the last data refresh

​
Agent Status Definitions

The agent has sent a heartbeat within the configured timeout window (default: 120 seconds). The agent is functioning normally.
The agent missed its expected heartbeat but has not exceeded the offline threshold (default: 5 minutes). This may indicate network issues or high load.
The agent has not sent a heartbeat beyond the offline threshold. It may be stopped, crashed, or the machine is unreachable.
Use this endpoint to build custom dashboards or integrate with monitoring tools like Grafana. Poll at a reasonable interval (every 30—60 seconds) to keep data fresh without overloading the API.

​
Integration Example

Here is a minimal dashboard polling script: 
async function pollDashboard() {
  const response = await fetch('https://localhost:8443/api/overview', {
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' },
  });
  const { data } = await response.json();

  // Alert if any agents are offline
  if (data.offlineAgents > 0) {
    console.warn(`${data.offlineAgents} agent(s) offline`);
  }

  // Alert on critical threats
  if (data.threatSummary.last24h.critical > 0) {
    console.warn(`${data.threatSummary.last24h.critical} critical threat(s) in last 24h`);
  }
}

// Poll every 60 seconds
setInterval(pollDashboard, 60_000);
pollDashboard();
For real-time updates without polling, use the SSE event stream instead.