# 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](https://sparklogs.com/docs/it-fleet-intelligence/connect.md) or open the device in the app.

## What the token needs

| Give a workspace token | With the scope |
| - | - |
| Any role that can read organizations and agents, such as **Auditor**, at the organizations you report on | `workspace:read` |

## Count agents by state

**`GET /workspaces/{workspace_id}/agents/summary`** [Count agents](https://sparklogs.com/docs/api/reference/agents.md#read-agent-summary)

Scope: `workspace:read`

```bash
curl -X GET \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/summary" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "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:

| Field | Counts |
| - | - |
| `enrolled` | Agents that are not deleted. Every other count is of these agents. |
| `active` | Agents created, or sending data, since `active_since` (14 days ago by default). |
| `inactive` | Agents created more than 14 days ago with no check-in, data or status change since. |
| `by_agent_status` | Agents at each `agent_status` value, such as `online`, `offline` or `stopped`. |
| `by_collection_status` | Agents 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](https://sparklogs.com/docs/api/reference/ingest-keys.md#list-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](https://sparklogs.com/docs/api/reference/agents.md#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.

```bash
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)

```json
{
  "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:

| Question | Field | Read it as |
| - | - | - |
| Is the agent there? | `agent_status` | `online` 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](https://sparklogs.com/docs/api/reference/agents.md) lists every value. |
| Is it collecting? | `collection_status` | `healthy`, `behind`, `onboarding`, `degraded` or `unknown`. Read `stuck_reason` for the cause. |
| Is data arriving? | `last_data_at` | When 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_state` | The 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](https://sparklogs.com/docs/api/reference/organizations.md#list-organizations)

Scope: `workspace:read`

```bash
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)

```json
{
  "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

| Call | Response | Cause |
| - | - | - |
| Count agents | 403 naming `agent.read` | The token can reach no organization. |
| Count agents | 400 naming `organization_id` | The organization is deleted, or `subtree` was sent without `organization_id`. |
| Count agents | 404 | The token cannot see that organization. |
| List agents | 200 with an empty list | No agent the token can see matches the filters. |

---

Source: <https://sparklogs.com/docs/api/use-cases/agent-collection-health>
All SparkLogs documentation in Markdown: <https://sparklogs.com/llms.txt>
