Skip to main content

Pull Agent Collection Health into a Dashboard

An agent that stops reporting is a device you can no longer see. This example shows how to count agents by state and list the agents that need attention, so that a dashboard can show the counts or your PSA can raise a ticket.

The calls here report whether each agent is present and collecting. They do not return disk, CPU, patch or event data. For those, connect an AI assistant or open the device in the app.

What the token needs​

Give a workspace tokenWith the scope
Any role that can read organizations and agents, such as Auditor, at the organizations you report onworkspace:read

Count agents by state​

GET/workspaces/{workspace_id}/agents/summary
Count agents

Scope: workspace:read

Request
curl -X GET \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/summary" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "agent_summary": {    "as_of": "2026-11-10T15:00:00Z",    "active_since": "2026-10-27T15:00:00Z",    "inactive_before": "2026-10-27T15:00:00Z",    "enrolled": 3,    "active": 3,    "inactive": 0,    "by_agent_status": {      "online": 2,      "offline": 0,      "never_seen": 0,      "stopped": 1,      "system_shutdown": 0,      "uninstalled": 0,      "upgrading_overdue": 0    },    "by_collection_status": {      "healthy": 1,      "behind": 1,      "onboarding": 0,      "degraded": 0,      "unknown": 1,      "none": 0    }  },  "message": "summary retrieved"}

One call returns counts and no list of agents:

FieldCounts
enrolledAgents that are not deleted. Every other count is of these agents.
activeAgents created, or sending data, since active_since (14 days ago by default).
inactiveAgents created more than 14 days ago with no check-in, data or status change since.
by_agent_statusAgents at each agent_status value, such as online, offline or stopped.
by_collection_statusAgents at each collection_status value, such as healthy or behind.

Pass organization_id with subtree=true to count one client. A response has no breakdown by client: to count every client, make one call for each. The summary counts agents only. To check ingest keys, list the ingest keys and read each key's data_status.

List the agents that need attention​

Each count in the summary is a value the list of agents filters by, so ask for only the agents that have a problem.

Agents that are not collecting as they should:

GET/workspaces/{workspace_id}/agents
List agents

Scope: workspace:read

Pass every collection_status value except healthy. none matches an agent with no collection status yet. Name the fields your dashboard shows in fields, with collection_detail among them.

Request
curl -X GET \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents?collection_status=behind%2Cdegraded%2Cunknown%2Cnone&fields=id%2Corganization_id%2Creported_hostname%2Crmm_device_id%2Cagent_status%2Ccollection_status%2Ccollection_detail%2Cstuck_reason%2Clast_data_at%2Clast_heartbeat_at" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "agents": [    {      "id": "a9e70000-0000-4000-8000-000000000203",      "organization_id": "0a9e0000-0000-4000-8000-000000000105",      "agent_status": "stopped",      "collection_status": "unknown",      "stuck_reason": null,      "last_data_at": "2026-11-09T18:00:00Z",      "last_heartbeat_at": "2026-11-09T18:00:00Z",      "reported_hostname": "pd-exam-03",      "rmm_device_id": null,      "collection_detail": null    },    {      "id": "a9e70000-0000-4000-8000-000000000202",      "organization_id": "0a9e0000-0000-4000-8000-000000000103",      "agent_status": "online",      "collection_status": "behind",      "stuck_reason": null,      "last_data_at": "2026-11-10T14:00:00Z",      "last_heartbeat_at": "2026-11-10T15:00:00Z",      "reported_hostname": "wb-pc-04",      "rmm_device_id": null,      "collection_detail": null    }  ],  "as_of": "2026-11-10T15:05:00Z",  "message": "agents retrieved",  "next_cursor": null}

Agents that are not online take the same call with a different filter: pass every agent_status value except online. Filters combine, and an agent must pass every one, so make one list for each question.

Do not list every agent and filter in your own code, and do not read agents one at a time. fields returns the detail behind each problem in the list itself. On a healthy fleet the two filtered lists are short, however many agents you have.

For each agent in a list:

QuestionFieldRead it as
Is the agent there?agent_statusonline while the agent is checking in, about every five minutes. offline once 15 minutes pass with no check-in and no data. Other values give the reason the agent is absent, such as stopped, system_shutdown, uninstalled or never_seen. The agent reference lists every value.
Is it collecting?collection_statushealthy, behind, onboarding, degraded or unknown. Read stuck_reason for the cause.
Is data arriving?last_data_atWhen log data last arrived. It can be old on a quiet machine that is otherwise fine.
What state did the agent's service last report?reported_stateThe last state the agent's service reported. A machine that was switched off can still read as running.

Read agent_status and collection_status separately. A laptop that is switched off is absent, and its collection may have been healthy when it last reported.

A laptop that is off overnight also shows in the list of agents that are not online. To raise a ticket only for a device that has been silent for longer, three days for example, add inactive_before with that cutoff, or filter by host_class to watch servers alone.

To turn an agent into a ticket for the right client, map organization_id to the organization's psa_client_id:

GET/workspaces/{workspace_id}/organizations
List organizations

Scope: workspace:read

Request
curl -X GET \  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/organizations?limit=2" \  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
Response 200
{  "message": "organizations retrieved",  "next_cursor": "eyJ2IjoxLCJleGFtcGxlIjp0cnVlfQ",  "organizations": [    {      "id": "0a9e0000-0000-4000-8000-000000000100",      "parent_id": null,      "path": [        "0a9e0000-0000-4000-8000-000000000100"      ],      "name": "Northwind clients",      "description": "Every client of Northwind IT Services",      "rmm_client_id": null,      "psa_client_id": null,      "created_at": "2026-11-01T09:00:00Z",      "updated_at": "2026-11-01T09:00:00Z",      "deleted_at": null    },    {      "id": "0a9e0000-0000-4000-8000-000000000101",      "parent_id": "0a9e0000-0000-4000-8000-000000000100",      "path": [        "0a9e0000-0000-4000-8000-000000000100",        "0a9e0000-0000-4000-8000-000000000101"      ],      "name": "Lakeside Clinic",      "description": "Family practice, two sites",      "rmm_client_id": "LAKESIDE-01",      "psa_client_id": "10042",      "created_at": "2026-11-02T09:00:00Z",      "updated_at": "2026-11-02T09:00:00Z",      "deleted_at": null    }  ],  "watermark": "2026-11-10T09:00:00Z"}

An agent also carries rmm_device_id and psa_device_id when your installer or your automation set them, so a ticket can name the device by your RMM's or PSA's own id.

How often to poll​

Poll no more often than every five minutes. Agents check in about every five minutes, so polling more often shows nothing new. A page holds 1,000 agents by default and up to 5,000 with limit. Every page of one list is worked out at the same moment (as_of), so an agent appears once however long paging takes.

If a call fails​

CallResponseCause
Count agents403 naming agent.readThe token can reach no organization.
Count agents400 naming organization_idThe organization is deleted, or subtree was sent without organization_id.
Count agents404The token cannot see that organization.
List agents200 with an empty listNo agent the token can see matches the filters.