# Agents

An agent is a SparkLogs Agent on a machine; list them, read one, count them by enrollment, activity, contact and collection, and rename, move, delete or restore one.

Agents and ingest keys are separate: an ingest key's id names no agent here, and returns 404 to a read and 403 to a change, as an id that does not exist does.

An agent's name follows its machine's host name until someone sets a different name; to make it follow again, set the name to the current `reported_hostname`, in any case. To label an agent and keep its name following, use `description`.

Belongs to: [Workspaces](https://sparklogs.com/docs/api/reference/workspaces.md), [Organizations](https://sparklogs.com/docs/api/reference/organizations.md), [Registration tokens](https://sparklogs.com/docs/api/reference/registration-tokens.md)

Ids: uuid.

- `GET /workspaces/{workspace_id}/agents` [List agents](#list-agents)
- `GET /workspaces/{workspace_id}/agents/{id}` [Read an agent](#read-agent)
- `GET /workspaces/{workspace_id}/agents/summary` [Count agents](#read-agent-summary)
- `PATCH /workspaces/{workspace_id}/agents/{id}` [Update an agent](#update-agent)
- `DELETE /workspaces/{workspace_id}/agents/{id}` [Delete an agent](#delete-agent)
- `POST /workspaces/{workspace_id}/agents/{id}/restore` [Restore a deleted agent](#restore-agent)
- `POST /workspaces/{workspace_id}/agents/{id}/move` [Move an agent](#move-agent)

## Agent object

An agent is a SparkLogs Agent installed on a machine: it reports whether it is in contact and how its collection stands.

- `id` (uuid): The agent's id.
- `workspace_id` (uuid): The workspace the agent belongs to.
- `name` (string or null): The agent's name. It starts as the host name the agent registered with, as the machine spells it, and follows the host name until someone sets a different name: a check-in reporting a new host name renames the agent, which waits while two machines share the agent's identity. To make it follow again, set the name to the current `reported_hostname`, in any case. To label an agent and keep its name following the host name, use `description`.
- `organization_id` (uuid): The organization the agent belongs to.
- `path` (array of uuid or null): The organization ids from the top-level organization down to the agent's own, then the agent's id.
- `reported_state` (string or null): The last service state the agent reported, such as running or stopped; unregistered until it first checks in. It is what the agent last said, not whether it is in contact now: a machine that lost power still shows running. `agent_status` says whether it is in contact. More values may be added.
- `agent_status` (one of the values below): Whether the agent is in contact, worked out from what it last announced and when anything last arrived from it: on a list at the page's `as_of`, the same instant for every page of one walk, and on a read of one agent when the response is written. It does not change `updated_at`. The same value the SparkLogs MCP server sends. It says nothing about collection: see `collection_status`. These are the values it takes today.
  - `online`: The agent checked in or sent data in the last 15 minutes.
  - `offline`: Nothing has arrived for longer than that, and the agent did not say it was stopping; the cause is unknown.
  - `never_seen`: Enrolled, and nothing has arrived from it yet.
  - `stopped`: The agent said its service was stopped.
  - `system_shutdown`: The agent said its machine was shutting down.
  - `uninstalled`: The agent said it was being uninstalled.
  - `upgrading_overdue`: The agent said it was updating itself and has not come back after 30 minutes.
  - `deleted`: The agent is deleted.
- `reported_state_changed_at` (date-time or null): When `reported_state` last changed.
- `collection_status` (string or null): SparkLogs' rollup of the agent's collection health across its feeds, worked out from what the agent last reported: healthy, behind, onboarding, degraded or unknown, and more values may be added. Null until first worked out; null and unknown never mean healthy.
- `stuck_reason` (string or null): Why the agent is checking in but not collecting; null while it collects.
- `last_data_at` (date-time or null): When log data from the agent last arrived, recorded at most once every five minutes. It is legitimately old on a quiet, healthy machine. Null until data first arrives.
- `last_heartbeat_at` (date-time or null): When the agent last checked in, about every five minutes while it runs. Null until it first checks in.
- `host_class` (string or null): The kind of machine the agent runs on: workstation or server today, and more values may be added.
- `reported_hostname` (string or null): The host name the agent reported, in lower case.
- `rmm_device_id` (string or null): The id your RMM uses for the agent's machine, as the installer was given it or as set later; null when none is recorded. Not unique, and it decides nothing about where the agent belongs or who may act on it.
- `psa_device_id` (string or null): The id your PSA uses for the agent's machine, as the installer was given it or as set later; null when none is recorded. Not unique, and it decides nothing about where the agent belongs or who may act on it.
- `agent_version` (string or null): The agent's version.
- `os_family` (string or null): The operating system family the agent reported.
- `os_version` (string or null): The operating system version the agent reported.
- `created_at` (date-time): When the agent was created.
- `updated_at` (date-time): When the agent's record last changed. Every check-in changes it, and so does arriving log data, so it says little about when anything else about the agent changed.
- `deleted_at` (date-time or null): When the agent was deleted; null while it is live.
- `organization_deleted_at` (date-time or null): When the agent's organization was deleted; null while the organization is live.
- `description` (string or null): The agent's description.
- `collection_detail` (any or null): The detail behind `collection_status`, as SparkLogs worked it out from the agent's last report. Its contents are not part of the API contract and may change.
- `collection_feeds` (map of any or null): How many of the agent's active feeds report each health, from the same report as `collection_status`. Keys: current, behind, stuck, blocked, onboarding, onboarding_stuck, unknown, and unrecognized for any other value. A health no feed reports is left out. Null when the agent has reported no feeds.
- `update_status` (string or null): Where the agent's automatic update stands: `idle`, `disabled`, `in_progress`, `reboot_pending` or `failure`; null for an agent that has not reported.
- `update_failure_reason` (string or null): Why the agent's last update failed, when it did.
- `install_id` (string or null): The id of the machine the agent is installed on, which stays the same when the agent registers again.
- `synthetic_install_id` (string or null): The agent's `install_id` when SparkLogs assigned it, because too many machines reported the same machine identity; null when the agent uses its machine's own id.
- `rollout_seed` (integer or null): The agent's place, from 0 to 999999, in a staged update rollout.
- `arch` (string or null): The processor architecture the agent reported.
- `host_roles` (array of string or null): The roles the agent reported for its machine; more values may be added.
- `registration_token_id` (uuid or null): The registration token the agent registered with.
- `cloned_from_agent_id` (uuid or null): The agent this one replaced when its machine was found to be a copy of another; null otherwise.
- `feed_pack_version` (string or null): The version of the collection definitions the agent last applied.
- `last_meta_at` (date-time or null): When SparkLogs last stored the agent's operating system and host details, which it refreshes at most every 15 minutes.
- `deletion` (AgentDeletion or null): What deleting the agent recorded: whether its machine heard the delete, and when the install comes off. Null while the agent is live.
- `custom_fields` (map of any or null): Custom fields recorded on the agent, as an object of string, number and boolean values. Not for secrets: anyone who may read the agent may read them.
- `host_metadata` (any or null): The machine details the agent last reported, as an object. Its contents are not part of the API contract and may change.
- `agent_data` (any or null): What the agent reported about its collection and updates, as an object. Large: it can hold tens of kilobytes per agent. Its contents are not part of the API contract and may change.

## List agents

`GET https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/agents`

Preview

Returns the SparkLogs Agents you can see, a page at a time, in `id` order. Seeing an agent takes `organization.read` and `agent.read` at its organization. Filter by organization, with or without the organizations below it, by id, status, inactivity, host, device id or registration token; filters combine, a row passing every one given. `agent_status` and a moving `inactive_before` cutoff, such as 14 days before now, are worked out at the walk's `as_of`, the same instant for every page. `host_metadata`, `agent_data` and `custom_fields` are sent only when `fields` names them, at most 500 agents a page.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `workspace:read`
- Privilege: `agent.read`

Needs `agent.read`. `agent.read` applies at each organization a grant covers and every organization below it. `agent.read` also admits reading ingest keys, but never their secrets. A caller who reaches no organization gets an empty list.

### Behavior

- Retry: Safe to send again
- Paging: Cursor · 1000 a page by default, up to 5000

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.

### Query parameters

- `organization_id` (uuid): Only agents of this organization.
- `subtree` (boolean): `true` adds the agents of every organization below `organization_id`. `true` and `false` are the only values it takes.
  Default: `false`
- `id` (array of string): Only the agents with these ids. A comma-separated list of at most 100 ids matches any of them.
- `agent_status` (array of one of the values below): Only agents reading one of these `agent_status` values. Deleted agents are listed with `deleted`, not here. A comma-separated list matches any of its values. Worked out at the walk's `as_of`.
  - `online`: Checked in or sent data in the last 15 minutes.
  - `offline`: Nothing has arrived for longer than that, and the agent did not say it was stopping.
  - `never_seen`: Enrolled, and nothing has arrived from it yet.
  - `stopped`: The agent said its service was stopped.
  - `system_shutdown`: The agent said its machine was shutting down.
  - `uninstalled`: The agent said it was being uninstalled.
  - `upgrading_overdue`: The agent said it was updating itself and has not come back after 30 minutes.
- `collection_status` (array of one of the values below): Only agents reporting one of these `collection_status` values, the same buckets `read-agent-summary` counts. A comma-separated list matches any of its values.
  - `healthy`: The agent reports `healthy`.
  - `behind`: The agent reports `behind`.
  - `onboarding`: The agent reports `onboarding`.
  - `degraded`: The agent reports `degraded`.
  - `unknown`: The agent reports `unknown`.
  - `none`: No collection status worked out yet: `collection_status` is null.
- `inactive_before` (date-time): Only agents that were created, last sent data, last checked in and last changed status before this time: what `inactive` counts on `read-agent-summary`, at a cutoff you choose. An RFC 3339 time.
- `host_class` (array of string): Only agents of these `host_class` values, such as server. A value no agent reports matches nothing. A comma-separated list matches any of its values, each exactly and ignoring case. Spaces around the value are ignored.
- `install_id` (string): Only agents with this `install_id`: every record of one machine, such as the live one a refused restore or move conflicts with. Spaces around the value are ignored.
- `reported_hostname` (string): Only agents whose `reported_hostname` is this. Matched exactly, ignoring case; every match you can see is returned. Spaces around the value are ignored.
- `registration_token_id` (uuid): Only agents that registered with this registration token.
- `rmm_device_id` (string): Only agents recording this `rmm_device_id`; every one is returned. Spaces around the value are ignored.
- `psa_device_id` (string): Only agents recording this `psa_device_id`; every one is returned. Spaces around the value are ignored.
- `deleted` (one of the values below): Which agents to list, by whether they or their organization are deleted.
  Default: `exclude`
  - `exclude`: Agents that are live in a live organization. The default.
  - `include`: Every agent, deleted ones and those of deleted organizations included.
  - `only`: Agents that are deleted or whose organization is.
- `limit` (integer): How many agents a page holds: 1 to 5000, 1000 by default; at most 500, and 500 by default, with a heavy field.
  Default: `1000` · 1 to 5000
- `cursor` (string): The `next_cursor` of the previous page, with the same filters.
- `fields` (array of string): Comma-separated top-level fields of each object to return instead of the default set.

Sent by default: `id`, `workspace_id`, `name`, `organization_id`, `path`, `reported_state`, `agent_status`, `reported_state_changed_at`, `collection_status`, `stuck_reason`, `last_data_at`, `last_heartbeat_at`, `host_class`, `reported_hostname`, `rmm_device_id`, `psa_device_id`, `agent_version`, `os_family`, `os_version`, `created_at`, `updated_at`, `deleted_at`, `organization_deleted_at`

Sent only when named in `fields`: `description`, `collection_detail`, `collection_feeds`, `update_status`, `update_failure_reason`, `install_id`, `synthetic_install_id`, `rollout_seed`, `arch`, `host_roles`, `registration_token_id`, `cloned_from_agent_id`, `feed_pack_version`, `last_meta_at`, `deletion`, `custom_fields`, `host_metadata`, `agent_data`

### Response (200)

- `agents` (array of Agent, required): The agents on this page.
- `next_cursor` (string or null, required): Null on the last page. Otherwise pass it as `cursor` for the next page.
- `as_of` (date-time, required): The instant this walk's values worked out from the clock, and its filters on them, are worked out at: fixed on the first page and the same on every page after it.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A query parameter it does not take, one given twice, or `fields` naming a field it does not have. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A filter's value is empty, names an empty item, is not one of the values the filter takes, or is not an id or a time where the filter asks for one; `parameter` names the filter. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `organization_id` is not a UUID, `subtree` is neither `true` nor `false` or comes without `organization_id`, `deleted` is not a value it takes, or `limit` is out of range, or `cursor` cannot be read or was sent with other filters. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `organization.read` and `agent.read`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [Read an agent](https://sparklogs.com/docs/api/reference/agents.md#read-agent)
- [Count agents](https://sparklogs.com/docs/api/reference/agents.md#read-agent-summary)
- [Update an agent](https://sparklogs.com/docs/api/reference/agents.md#update-agent)
- [Delete an agent](https://sparklogs.com/docs/api/reference/agents.md#delete-agent)
- [Restore a deleted agent](https://sparklogs.com/docs/api/reference/agents.md#restore-agent)
- [Move an agent](https://sparklogs.com/docs/api/reference/agents.md#move-agent)

### Example

List every agent a read-only personal token can see

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

Response (200)

```json
{
  "agents": [
    {
      "id": "a9e70000-0000-4000-8000-000000000203",
      "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
      "name": "PD-EXAM-03",
      "organization_id": "0a9e0000-0000-4000-8000-000000000105",
      "path": [
        "0a9e0000-0000-4000-8000-000000000100",
        "0a9e0000-0000-4000-8000-000000000105",
        "a9e70000-0000-4000-8000-000000000203"
      ],
      "reported_state": "stopped",
      "agent_status": "stopped",
      "reported_state_changed_at": "2026-11-09T18:00:00Z",
      "collection_status": "unknown",
      "stuck_reason": null,
      "last_data_at": "2026-11-09T18:00:00Z",
      "last_heartbeat_at": "2026-11-09T18:00:00Z",
      "host_class": "workstation",
      "reported_hostname": "pd-exam-03",
      "rmm_device_id": null,
      "psa_device_id": null,
      "agent_version": "1.14.3",
      "os_family": "windows",
      "os_version": "10.0.22631",
      "created_at": "2026-11-05T08:00:00Z",
      "updated_at": "2026-11-09T18:00:00Z",
      "deleted_at": null,
      "organization_deleted_at": null
    },
    {
      "id": "a9e70000-0000-4000-8000-000000000201",
      "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
      "name": "FIN-LT-04",
      "organization_id": "0a9e0000-0000-4000-8000-000000000102",
      "path": [
        "0a9e0000-0000-4000-8000-000000000100",
        "0a9e0000-0000-4000-8000-000000000101",
        "0a9e0000-0000-4000-8000-000000000102",
        "a9e70000-0000-4000-8000-000000000201"
      ],
      "reported_state": "running",
      "agent_status": "online",
      "reported_state_changed_at": "2026-11-03T12:00:00Z",
      "collection_status": "healthy",
      "stuck_reason": null,
      "last_data_at": "2026-11-10T15:00:00Z",
      "last_heartbeat_at": "2026-11-10T15:00:00Z",
      "host_class": "workstation",
      "reported_hostname": "fin-lt-04",
      "rmm_device_id": null,
      "psa_device_id": null,
      "agent_version": "1.14.4",
      "os_family": "windows",
      "os_version": "10.0.22631",
      "created_at": "2026-11-03T12:00:00Z",
      "updated_at": "2026-11-10T15:00:00Z",
      "deleted_at": null,
      "organization_deleted_at": null
    },
    {
      "id": "a9e70000-0000-4000-8000-000000000202",
      "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
      "name": "wb-pc-04",
      "organization_id": "0a9e0000-0000-4000-8000-000000000103",
      "path": [
        "0a9e0000-0000-4000-8000-000000000100",
        "0a9e0000-0000-4000-8000-000000000103",
        "a9e70000-0000-4000-8000-000000000202"
      ],
      "reported_state": "running",
      "agent_status": "online",
      "reported_state_changed_at": "2026-11-04T09:00:00Z",
      "collection_status": "behind",
      "stuck_reason": null,
      "last_data_at": "2026-11-10T14:00:00Z",
      "last_heartbeat_at": "2026-11-10T15:00:00Z",
      "host_class": "workstation",
      "reported_hostname": "wb-pc-04",
      "rmm_device_id": null,
      "psa_device_id": null,
      "agent_version": "1.14.4",
      "os_family": "windows",
      "os_version": "10.0.19045",
      "created_at": "2026-11-04T09:00:00Z",
      "updated_at": "2026-11-10T15:00:00Z",
      "deleted_at": null,
      "organization_deleted_at": null
    }
  ],
  "as_of": "2026-11-10T15:05:00Z",
  "message": "agents retrieved",
  "next_cursor": null
}
```

## Read an agent

`GET https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/agents/{id}`

Preview

Returns one SparkLogs Agent you can see, deleted or not, with every field but `collection_detail`, `rollout_seed`, `host_metadata`, `agent_data` and `custom_fields` unless `fields` names them. One you cannot see returns 404, as one that does not exist does, and so does the id of an ingest key.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `workspace:read`
- Privilege: `agent.read`

Needs `agent.read`. `agent.read` applies at each organization a grant covers and every organization below it. `agent.read` also admits reading ingest keys, but never their secrets.

### Behavior

- Retry: Safe to send again

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.
- `id` (uuid, required): The agent's id.

### Query parameters

- `fields` (array of string): Comma-separated top-level fields of each object to return instead of the default set.

Sent by default: `id`, `workspace_id`, `name`, `organization_id`, `path`, `reported_state`, `agent_status`, `reported_state_changed_at`, `collection_status`, `stuck_reason`, `last_data_at`, `last_heartbeat_at`, `host_class`, `reported_hostname`, `rmm_device_id`, `psa_device_id`, `agent_version`, `os_family`, `os_version`, `created_at`, `updated_at`, `deleted_at`, `organization_deleted_at`, `description`, `collection_feeds`, `update_status`, `update_failure_reason`, `install_id`, `synthetic_install_id`, `arch`, `host_roles`, `registration_token_id`, `cloned_from_agent_id`, `feed_pack_version`, `last_meta_at`, `deletion`

Sent only when named in `fields`: `collection_detail`, `rollout_seed`, `custom_fields`, `host_metadata`, `agent_data`

### Response (200)

- `agent` (Agent, required): The agent.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A query parameter it does not take, one given twice, or `fields` naming a field it does not have. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `id` is not a UUID. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `organization.read` and `agent.read`. The same refusal comes when the path names a workspace other than the token's own. | No |
| 404 | `APP_API_ERR_RECORD_NOT_FOUND` | No such agent, or one you cannot see; an ingest key's id answers this too. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List agents](https://sparklogs.com/docs/api/reference/agents.md#list-agents)
- [Count agents](https://sparklogs.com/docs/api/reference/agents.md#read-agent-summary)
- [Update an agent](https://sparklogs.com/docs/api/reference/agents.md#update-agent)
- [Delete an agent](https://sparklogs.com/docs/api/reference/agents.md#delete-agent)
- [Restore a deleted agent](https://sparklogs.com/docs/api/reference/agents.md#restore-agent)
- [Move an agent](https://sparklogs.com/docs/api/reference/agents.md#move-agent)

### Example

Read an agent

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

Response (200)

```json
{
  "agent": {
    "id": "a9e70000-0000-4000-8000-000000000201",
    "workspace_id": "5e1f0a00-0000-4000-8000-000000000001",
    "name": "FIN-LT-04",
    "organization_id": "0a9e0000-0000-4000-8000-000000000102",
    "path": [
      "0a9e0000-0000-4000-8000-000000000100",
      "0a9e0000-0000-4000-8000-000000000101",
      "0a9e0000-0000-4000-8000-000000000102",
      "a9e70000-0000-4000-8000-000000000201"
    ],
    "reported_state": "running",
    "agent_status": "online",
    "reported_state_changed_at": "2026-11-03T12:00:00Z",
    "collection_status": "healthy",
    "stuck_reason": null,
    "last_data_at": "2026-11-10T15:00:00Z",
    "last_heartbeat_at": "2026-11-10T15:00:00Z",
    "host_class": "workstation",
    "reported_hostname": "fin-lt-04",
    "rmm_device_id": null,
    "psa_device_id": null,
    "agent_version": "1.14.4",
    "os_family": "windows",
    "os_version": "10.0.22631",
    "created_at": "2026-11-03T12:00:00Z",
    "updated_at": "2026-11-10T15:00:00Z",
    "deleted_at": null,
    "organization_deleted_at": null,
    "description": null,
    "collection_feeds": null,
    "update_status": null,
    "update_failure_reason": null,
    "install_id": null,
    "synthetic_install_id": null,
    "arch": null,
    "host_roles": null,
    "registration_token_id": null,
    "cloned_from_agent_id": null,
    "feed_pack_version": null,
    "last_meta_at": null,
    "deletion": null
  },
  "message": "agent retrieved"
}
```

## Count agents

`GET https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/agents/summary`

Preview

Returns how many SparkLogs Agents you can see are enrolled, active since `active_since` and inactive, and how many read each `agent_status` and report each `collection_status`, worked out at one moment. It reports on the agents, and says nothing of the devices' own health, such as disk, CPU or patches. To list the agents behind a count, list the agents. Counting an agent takes `organization.read` and `agent.read` at its organization; a count never includes an agent you cannot see, and holding both nowhere together returns 403. Narrow it to an organization, with or without the organizations below it; a deleted one returns 400, since only live organizations are counted, and one you cannot see returns 404.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `workspace:read`
- Privilege: `agent.read`

Needs `agent.read`. `agent.read` applies at each organization a grant covers and every organization below it. `agent.read` also admits reading ingest keys, but never their secrets.

### Behavior

- Retry: Safe to send again

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.

### Query parameters

- `organization_id` (uuid): Only the agents of this organization.
- `subtree` (boolean): `true` adds the agents of every organization below `organization_id`. `true` and `false` are the only values it takes.
  Default: `false`
- `active_since` (date-time): Where the active count starts (RFC 3339), such as the start of the period a dashboard shows. 14 days before `as_of` by default.
- `fields` (array of string): Comma-separated top-level fields of each object to return instead of the default set.

Sent by default: `as_of`, `active_since`, `inactive_before`, `enrolled`, `active`, `inactive`, `by_agent_status`, `by_collection_status`

### Response (200)

- `agent_summary` (AgentSummary, required): The agent summary.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A query parameter it does not take, one given twice, or `fields` naming a field it does not have. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `organization_id` is not a UUID or names a deleted organization, `subtree` is neither `true` nor `false` or comes without it, or `active_since` is not a valid time. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE` (cause `token_scope` or `no_privilege`) | You do not hold `organization.read` and `agent.read` together at any organization. The same refusal comes when the path names a workspace other than the token's own. | No |
| 404 | `APP_API_ERR_RECORD_NOT_FOUND` | `organization_id` names an organization you cannot see. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List agents](https://sparklogs.com/docs/api/reference/agents.md#list-agents)
- [Read an agent](https://sparklogs.com/docs/api/reference/agents.md#read-agent)
- [Update an agent](https://sparklogs.com/docs/api/reference/agents.md#update-agent)
- [Delete an agent](https://sparklogs.com/docs/api/reference/agents.md#delete-agent)
- [Restore a deleted agent](https://sparklogs.com/docs/api/reference/agents.md#restore-agent)
- [Move an agent](https://sparklogs.com/docs/api/reference/agents.md#move-agent)

### Example

Count the agents you can see

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

## Update an agent

`PATCH https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/agents/{id}`

Preview

Changes a SparkLogs Agent's name, description, device ids or custom fields; a field left out keeps its value. The name follows the machine's host name until someone sets a different name; to make it follow again, set it to the current `reported_hostname`, in any case. To label an agent and keep its name following, set `description`. Needs `agent.write` at its organization.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `fleet:write`
- Privilege: `agent.write`

Needs `agent.write`. `agent.write` applies at each organization a grant covers and every organization below it. `agent.write` also admits changing and moving ingest keys.

### Behavior

- Retry: Safe to repeat: ends in the same state
- Audit log: Recorded

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.
- `id` (uuid, required): The agent's id.

### Request body

No field is required. Send no body to accept the defaults.

- `name` (string): The new name, cleaned as every name is. The name follows the machine's host name until a different name is set here; setting it to the current `reported_hostname`, in any case, makes it follow again. To label the agent and keep its name following, set `description` instead. `null` or an empty string returns 400.
  left out keeps · `null` is refused · empty string is refused
  at most 128 characters
- `description` (string or null): The new description. `null` or an empty string clears it.
  left out keeps · `null` clears · empty string clears
  at most 2048 characters
- `rmm_device_id` (string or null): The id your RMM uses for the agent's machine, cleaned as every name is. A later registration of the machine that names no id keeps it. `null` or an empty string clears it.
  left out keeps · `null` clears · empty string clears
  at most 256 characters
- `psa_device_id` (string or null): The id your PSA uses for the agent's machine, cleaned as every name is. A later registration of the machine that names no id keeps it. `null` or an empty string clears it.
  left out keeps · `null` clears · empty string clears
  at most 256 characters
- `custom_fields` (map of any or null): Changes to the custom fields, merged into the stored ones: a key left out keeps its value, null removes it, and a string, a boolean, or a number of at most 32 characters in plain decimal digits with no exponent sets it. A number is kept by its value, so 1.50 reads back as 1.5. At most 50 keys, each 1 to 64 letters, digits, `_`, `-` and `.`, and 8 KiB as JSON. Write a time as RFC 3339 in UTC. Not for secrets.

### Response (200)

- `id` (uuid, required): The id of the row the call created or changed.
- `cache_clear_status` (one of the values below, or null): Sent when the change has to reach every region's cache: how far it got.
  - `ok`: Every region's cache has the change.
  - `failed`: A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  - `disabled`: This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
- `cache_clear_message` (string or null): Sent with a `cache_clear_status` other than ok: what it means, for a person to read.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The URL carries a query parameter, which a write does not take: its fields come from its body. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `name` is empty. | No |
| 400 | `APP_API_ERR_PARAMETER_TOO_LONG` | `name` is longer than 128 characters, or `description` longer than 2048. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION` (cause `token_scope` or `no_privilege`) | The agent does not exist, is in another workspace or is outside your reach, `id` names an ingest key, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own. | No |
| 413 | `APP_API_ERR_BODY_TOO_LARGE` | The body is larger than 1 MiB. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List agents](https://sparklogs.com/docs/api/reference/agents.md#list-agents)
- [Read an agent](https://sparklogs.com/docs/api/reference/agents.md#read-agent)
- [Count agents](https://sparklogs.com/docs/api/reference/agents.md#read-agent-summary)
- [Delete an agent](https://sparklogs.com/docs/api/reference/agents.md#delete-agent)
- [Restore a deleted agent](https://sparklogs.com/docs/api/reference/agents.md#restore-agent)
- [Move an agent](https://sparklogs.com/docs/api/reference/agents.md#move-agent)

### Example

Rename an agent

```bash
curl -X PATCH \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/a9e70000-0000-4000-8000-000000000202" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "WB-PC-04 front desk"
  }'
```

Response (200)

```json
{
  "message": "agent updated",
  "id": "a9e70000-0000-4000-8000-000000000202"
}
```

## Delete an agent

`DELETE https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/agents/{id}`

Preview · Destructive

Marks a SparkLogs Agent deleted; its machine is refused from then on, and `cache_clear_status` says whether every region refuses it. The query parameter `uninstall` says when the machine removes the install: on that date the agent removes itself, with its local state when `uninstall_purge` is true, and left out the date is 60 days after the first delete. The options are query parameters because some HTTP clients and proxies drop or refuse a body on DELETE, which would delete the agent without scheduling its removal; a body is refused. Needs `agent.delete` at its organization. Deleting a deleted agent changes nothing, except that a named `uninstall` replaces the stored schedule. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 2 hours.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `fleet:write`
- Privilege: `agent.delete`

Needs `agent.delete`. `agent.delete` applies at each organization a grant covers and every organization below it. `agent.delete` also admits deleting and restoring ingest keys.

### Behavior

- Retry: Safe to repeat: ends in the same state
- Audit log: Recorded

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.
- `id` (uuid, required): The agent's id.

### Query parameters

- `uninstall` (one of the values below): When the agent's machine removes the install. Left out, a first delete records the default of 60 days and a repeated one keeps what is stored; given on a repeated delete, it replaces the stored schedule.
  - `after_days`: After the number of days in `uninstall_days`.
  - `immediately`: As soon as the agent learns of the delete.
  - `never`: The install stays on the machine.
- `uninstall_days` (integer): With `after_days`, how many days after the delete: 1 to 365, 60 by default.
  Default: `60` · 1 to 365
- `uninstall_purge` (boolean): `true` also deletes what the agent keeps on the machine: its settings, its identity, the events it buffered and not yet sent, and its logs. Left out, they stay, and installing the agent there again later carries on from them. `true` and `false` are the only values it takes.
  Default: `false`

### Response (200)

- `cache_clear_status` (one of the values below, or null): Sent when the change has to reach every region's cache: how far it got.
  - `ok`: Every region's cache has the change.
  - `failed`: A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  - `disabled`: This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
- `cache_clear_message` (string or null): Sent with a `cache_clear_status` other than ok: what it means, for a person to read.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | A query parameter it does not take, or one given twice. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `uninstall` is not one of the values it takes, `uninstall_days` is not a whole number from 1 to 365 or comes with `uninstall` other than `after_days`, `uninstall_purge` is not `true` or `false` or comes with `uninstall` `never`, or `uninstall_days` or `uninstall_purge` comes without `uninstall`; `parameter` names the parameter. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The request carries a body other than nothing, `null` or `{}`: a delete takes none, and its options are query parameters; `parameter` names the body's first field, or `body`. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION` (cause `token_scope` or `no_privilege`) | The agent does not exist, is in another workspace or is outside your reach, `id` names an ingest key, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own. | No |
| 413 | `APP_API_ERR_BODY_TOO_LARGE` | The body is larger than 1 MiB. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List agents](https://sparklogs.com/docs/api/reference/agents.md#list-agents)
- [Read an agent](https://sparklogs.com/docs/api/reference/agents.md#read-agent)
- [Count agents](https://sparklogs.com/docs/api/reference/agents.md#read-agent-summary)
- [Update an agent](https://sparklogs.com/docs/api/reference/agents.md#update-agent)
- [Restore a deleted agent](https://sparklogs.com/docs/api/reference/agents.md#restore-agent)
- [Move an agent](https://sparklogs.com/docs/api/reference/agents.md#move-agent)

### Example

Delete an agent and remove its install in 7 days

```bash
curl -X DELETE \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/a9e70000-0000-4000-8000-000000000203?uninstall=after_days&uninstall_days=7" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN"
```

Response (200)

```json
{
  "message": "agent deleted",
  "cache_clear_status": "ok"
}
```

## Restore a deleted agent

`POST https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/agents/{id}/restore`

Preview

Restores a deleted SparkLogs Agent. It cancels a pending uninstall; an agent already removed from its machine is not reinstalled. Another live agent in its organization with the same install id returns 409. Needs `agent.delete` at its organization. Restoring a live agent changes nothing. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 2 hours.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `fleet:write`
- Privilege: `agent.delete`

Needs `agent.delete`. `agent.delete` applies at each organization a grant covers and every organization below it. `agent.delete` also admits deleting and restoring ingest keys.

### Behavior

- Retry: Safe to repeat: ends in the same state
- Audit log: Recorded

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.
- `id` (uuid, required): The agent's id.

### Response (200)

- `cache_clear_status` (one of the values below, or null): Sent when the change has to reach every region's cache: how far it got.
  - `ok`: Every region's cache has the change.
  - `failed`: A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  - `disabled`: This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
- `cache_clear_message` (string or null): Sent with a `cache_clear_status` other than ok: what it means, for a person to read.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The URL carries a query parameter, which a write does not take: its fields come from its body. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The body is not a JSON object, is not sent as `application/json`, or names a field: the call takes none. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION` (cause `token_scope` or `no_privilege`) | The agent does not exist, is in another workspace or is outside your reach, `id` names an ingest key, or you do not hold the privilege at its organization. The same refusal comes when the path names a workspace other than the token's own. | No |
| 409 | `APP_API_ERR_CANNOT_RESTORE_PARENT_DELETED` | Its organization is deleted. | No |
| 409 | `APP_API_ERR_ALREADY_TAKEN` | Another live agent in its organization carries its machine's install id; `parameter` is `install_id`. | No |
| 413 | `APP_API_ERR_BODY_TOO_LARGE` | The body is larger than 1 MiB. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List agents](https://sparklogs.com/docs/api/reference/agents.md#list-agents)
- [Read an agent](https://sparklogs.com/docs/api/reference/agents.md#read-agent)
- [Count agents](https://sparklogs.com/docs/api/reference/agents.md#read-agent-summary)
- [Update an agent](https://sparklogs.com/docs/api/reference/agents.md#update-agent)
- [Delete an agent](https://sparklogs.com/docs/api/reference/agents.md#delete-agent)
- [Move an agent](https://sparklogs.com/docs/api/reference/agents.md#move-agent)

### Example

Restore a deleted agent

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

Response (200)

```json
{
  "message": "agent restored",
  "cache_clear_status": "ok"
}
```

## Move an agent

`POST https://engine.sparklogs.app/app-api/workspaces/{workspace_id}/agents/{id}/move`

Preview

Moves a SparkLogs Agent to another organization. Needs `agent.write` at its organization and `ingest_key.create` at the new one. Another live agent there with the same install id returns 409. Moving it where it already is changes nothing. When `cache_clear_status` is not `ok`, a region the change did not reach can act on the earlier state for up to 2 hours.

### Access

- Works with: Signed-in person, Personal token, OAuth token, Workspace token
- Scope: `fleet:write`
- Privilege: `agent.write`, `ingest_key.create`

Needs `agent.write` at the organization it is in now and `ingest_key.create` at the organization it moves to. `agent.write` applies at each organization a grant covers and every organization below it. `agent.write` also admits changing and moving ingest keys. `ingest_key.create` applies at each organization a grant covers and every organization below it. `ingest_key.create` also admits moving a SparkLogs Agent or an ingest key into an organization, with `agent.write` at the one it leaves.

### Behavior

- Retry: Safe to repeat: ends in the same state
- Audit log: Recorded

### Path parameters

- `workspace_id` (uuid, required): The workspace's id.
- `id` (uuid, required): The agent's id.

### Request body

- `organization_id` (uuid, required): The organization to move it to. Moving needs `agent.write` at the agent's organization and `ingest_key.create` at this one. Required.

### Response (200)

- `cache_clear_status` (one of the values below, or null): Sent when the change has to reach every region's cache: how far it got.
  - `ok`: Every region's cache has the change.
  - `failed`: A region could not be reached. The change is saved, and that region can act on the earlier state until its cache expires.
  - `disabled`: This environment does not clear regional caches. The change is saved, and each region can act on the earlier state until its cache expires.
- `cache_clear_message` (string or null): Sent with a `cache_clear_status` other than ok: what it means, for a person to read.
- `message` (string, required): What the call did, as a short phrase for a person to read. Its wording may change: act on the HTTP status.

### Errors

| Status | Code | When | Send again? |
| - | - | - | - |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The URL carries a query parameter, which a write does not take: its fields come from its body. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `workspace_id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `id` is not a UUID. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | The body is not a JSON object, is not sent as `application/json`, names a field the call does not take, or a field has the wrong type; `parameter` names the field, or `Content-Type`. | No |
| 400 | `APP_API_ERR_MISSING_PARAMETER` | `organization_id` is left out. | No |
| 400 | `APP_API_ERR_BAD_PARAMETERS` | `organization_id` is not a UUID, or names a deleted organization for a live agent. | No |
| 401 | `APP_API_ERR_UNAUTHORIZED` | The token is missing, not valid, expired or revoked, or its workspace is deleted. | No |
| 403 | `APP_API_ERR_NO_PRIVILEGE_ON_THIS_ORGANIZATION` (cause `token_scope` or `no_privilege`) | The agent or the new organization does not exist or is outside your reach, `id` names an ingest key, or you do not hold `agent.write` at the agent's organization and `ingest_key.create` at the new one. The same refusal comes when the path names a workspace other than the token's own. | No |
| 409 | `APP_API_ERR_ALREADY_TAKEN` | Another live agent in the new organization carries the agent's machine install id; `parameter` is `install_id`. | No |
| 413 | `APP_API_ERR_BODY_TOO_LARGE` | The body is larger than 1 MiB. | No |
| 429 | `APP_API_ERR_TOO_MANY_REQUESTS` (cause `call_limit` or `invalid_token_attempts`) | The token made more calls than its limit (`cause` `call_limit`; `Retry-After` says when to try again), or the address it came from sent too many tokens that are not valid (`cause` `invalid_token_attempts`). | After `Retry-After` |
| 500 | `APP_API_ERR_TECHNICAL_ISSUE` | The call failed on the server. | Read first |
| 503 | `APP_API_ERR_MAINTENANCE` | SparkLogs is in scheduled maintenance. | After `Retry-After` |

Every call can also return the [common errors](https://sparklogs.com/docs/api/errors.md).

### Related

- [List agents](https://sparklogs.com/docs/api/reference/agents.md#list-agents)
- [Read an agent](https://sparklogs.com/docs/api/reference/agents.md#read-agent)
- [Count agents](https://sparklogs.com/docs/api/reference/agents.md#read-agent-summary)
- [Update an agent](https://sparklogs.com/docs/api/reference/agents.md#update-agent)
- [Delete an agent](https://sparklogs.com/docs/api/reference/agents.md#delete-agent)
- [Restore a deleted agent](https://sparklogs.com/docs/api/reference/agents.md#restore-agent)

### Example

Move an agent to Lakeside Clinic

```bash
curl -X POST \
  "https://engine.sparklogs.app/app-api/workspaces/5e1f0a00-0000-4000-8000-000000000001/agents/a9e70000-0000-4000-8000-000000000202/move" \
  -H "Authorization: Bearer $SPARKLOGS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "0a9e0000-0000-4000-8000-000000000101"
  }'
```

Response (200)

```json
{
  "message": "agent moved",
  "cache_clear_status": "ok"
}
```

## AgentDeletion object

- `dormant_since` (date-time or null, required): When the machine reported it heard the delete; null until it does.
- `uninstall_after` (date-time or null, required): When the install comes off; null when it stays or none is recorded.
- `uninstall_never` (boolean, required): Whether the install stays.
- `uninstall_purge` (boolean, required): Whether local state goes with it.

## AgentSummary object

- `as_of` (date-time): The time every count and cutoff below is worked out against.
- `active_since` (date-time): Where the active count starts: the `active_since` you sent, or 14 days before `as_of`.
- `inactive_before` (date-time): 14 days before `as_of`. An agent is inactive when it was created, last sent data, last checked in and last changed status before this time.
- `enrolled` (integer): How many SparkLogs Agents you can see that are not deleted, in organizations that are not deleted. Every count below is of these.
- `active` (integer): How many of them were created or sent data at or after `active_since`.
- `inactive` (integer): How many of them are inactive: nothing about them moved since `inactive_before`.
- `by_agent_status` (AgentStatusCounts): How many of them read each `agent_status` at `as_of`, as a list of agents shows it.
- `by_collection_status` (CollectionStatusCounts): How many of them report each `collection_status`.

## AgentStatusCounts object

- `online` (integer, required): Checked in or sent data in the last 15 minutes.
- `offline` (integer, required): Nothing has arrived for longer than that, and the agent did not say it was stopping.
- `never_seen` (integer, required): Enrolled, and nothing has arrived from it yet.
- `stopped` (integer, required): The agent said its service was stopped.
- `system_shutdown` (integer, required): The agent said its machine was shutting down.
- `uninstalled` (integer, required): The agent said it was being uninstalled.
- `upgrading_overdue` (integer, required): The agent said it was updating itself and has not come back after 30 minutes.

## CollectionStatusCounts object

- `healthy` (integer, required): How many report `healthy`.
- `behind` (integer, required): How many report `behind`.
- `onboarding` (integer, required): How many report `onboarding`.
- `degraded` (integer, required): How many report `degraded`.
- `unknown` (integer, required): How many report `unknown`.
- `none` (integer, required): No collection status worked out yet: `collection_status` is null.

---

Source: <https://sparklogs.com/docs/api/reference/agents>
All SparkLogs documentation in Markdown: <https://sparklogs.com/llms.txt>
