# Server groups and bulk actions

URL: https://docs.vaultpanel.net/api-reference/server-groups

> API reference for server groups and bulk actions, which run one operation on many servers at once, in parallel or one server at a time.

**Server groups** collect servers you watch and act on together, such as "Production" or "Frankfurt". A server can be in several groups. **Bulk actions** run one operation on a set of servers, or on a group, and track each server's part. See [Server groups](https://docs.vaultpanel.net/guides/servers/server-groups).

To change the groups of one server, use [`PUT /servers/:id/groups`](https://docs.vaultpanel.net/api-reference/servers#set-a-servers-groups).

## Endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/server-groups` | [List groups](https://docs.vaultpanel.net/api-reference/server-groups#list-groups) |
| POST | `/api/v1/server-groups` | [Create a group](https://docs.vaultpanel.net/api-reference/server-groups#create-a-group) |
| GET | `/api/v1/server-groups/:id` | [Get a group](https://docs.vaultpanel.net/api-reference/server-groups#get-a-group) |
| PATCH | `/api/v1/server-groups/:id` | [Update a group](https://docs.vaultpanel.net/api-reference/server-groups#update-a-group) |
| DELETE | `/api/v1/server-groups/:id` | [Delete a group](https://docs.vaultpanel.net/api-reference/server-groups#delete-a-group) |
| GET | `/api/v1/bulk-actions` | [List bulk actions](https://docs.vaultpanel.net/api-reference/server-groups#list-bulk-actions) |
| POST | `/api/v1/bulk-actions` | [Start a bulk action](https://docs.vaultpanel.net/api-reference/server-groups#start-a-bulk-action) |
| GET | `/api/v1/bulk-actions/:id` | [Get a bulk action](https://docs.vaultpanel.net/api-reference/server-groups#get-a-bulk-action) |
| POST | `/api/v1/bulk-actions/:id/cancel` | [Cancel a bulk action](https://docs.vaultpanel.net/api-reference/server-groups#cancel-a-bulk-action) |

## The group summary

Group responses include a `summary` of their servers. Averages and highest values use only servers that are online and have reported metrics.

```json
{
  "total": 3,
  "online": 3,
  "offline": 0,
  "pending": 0,
  "disabled": 0,
  "firingAlerts": 1,
  "agentsOutdated": 0,
  "cpu": { "average": 18.2, "max": 41.0 },
  "memory": { "average": 46.7, "max": 63.1 },
  "disk": { "average": 31.5, "max": 52.8 }
}
```

`cpu`, `memory` and `disk` are percentages, or `null` when no server has data.

## List groups

`GET /api/v1/server-groups` — Permission: servers.read — Token scope: read

Every group, by name, with its servers and summary.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/server-groups \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.servers.groups.list();
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "c2d4e6f8-1a3b-4c5d-9e7f-2b4d6f8a0c1e",
        "name": "Production",
        "description": "Customer-facing servers",
        "color": "green",
        "createdAt": "2026-10-22T09:00:00.000Z",
        "updatedAt": "2026-10-22T09:00:00.000Z",
        "servers": [{ "id": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b", "name": "web-1", "status": "online" }],
        "summary": { "total": 1, "online": 1, "offline": 0, "pending": 0, "disabled": 0, "firingAlerts": 0, "agentsOutdated": 0, "cpu": { "average": 12.4, "max": 12.4 }, "memory": { "average": 38.6, "max": 38.6 }, "disk": { "average": 24.5, "max": 24.5 } }
      }
    ]
  },
  "message": "OK",
  "requestId": "…"
}
```

This list is not paginated.

## Create a group

`POST /api/v1/server-groups` — Permission: servers.manage — Token scope: servers

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Up to 60 letters, numbers, spaces and `. _ - ( ) &`, starting with a letter or number. Unique. |
| `description` | string | No | Up to 300 characters. |
| `color` | string | No | `blue` (default), `green`, `amber`, `red`, `purple`, `teal` or `gray`. |
| `serverIds` | string[] | No | Up to 500 servers to put in the group. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/server-groups \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Production","color":"green","serverIds":["1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b"]}'
```

**JavaScript**

```js
const group = await panel.servers.groups.create({
  name: 'Production',
  color: 'green',
  serverIds: [serverId],
});
```

**Response** `201 Created` with the group, as from [Get a group](https://docs.vaultpanel.net/api-reference/server-groups#get-a-group).

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `GROUP_EXISTS` | A group with this name already exists. |
| 422 | `VALIDATION_ERROR` | A field is invalid, or one of the servers was not found. |

## Get a group

`GET /api/v1/server-groups/:id` — Permission: servers.read — Token scope: read

The group with its full server records: each server's fields, latest metrics, firing alert count and whether its agent is outdated.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/server-groups/c2d4e6f8-1a3b-4c5d-9e7f-2b4d6f8a0c1e \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const group = await panel.servers.groups.get(groupId);
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "id": "c2d4e6f8-1a3b-4c5d-9e7f-2b4d6f8a0c1e",
    "name": "Production",
    "description": "Customer-facing servers",
    "color": "green",
    "servers": [
      { "id": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b", "name": "web-1", "status": "online", "latestMetrics": { "cpuPercent": 12.4 }, "firingAlerts": 0, "agentOutdated": false }
    ],
    "summary": { "total": 1, "online": 1, "offline": 0, "pending": 0, "disabled": 0, "firingAlerts": 0, "agentsOutdated": 0, "cpu": { "average": 12.4, "max": 12.4 }, "memory": { "average": 38.6, "max": 38.6 }, "disk": { "average": 24.5, "max": 24.5 } }
  },
  "message": "OK",
  "requestId": "…"
}
```

Each server carries every field of [the server object](https://docs.vaultpanel.net/api-reference/servers#the-server-object).

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such group. |

## Update a group

`PATCH /api/v1/server-groups/:id` — Permission: servers.manage — Token scope: servers

Changes any of `name`, `description`, `color` and `serverIds` (same rules as [Create a group](https://docs.vaultpanel.net/api-reference/server-groups#create-a-group)). `serverIds` replaces the whole membership. Send at least one field.

**Example request**

**cURL**

```bash
curl -X PATCH https://panel.example.com/api/v1/server-groups/c2d4e6f8-1a3b-4c5d-9e7f-2b4d6f8a0c1e \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"description":"Customer-facing servers in Frankfurt"}'
```

**JavaScript**

```js
const group = await panel.servers.groups.update(groupId, { description: 'Customer-facing servers in Frankfurt' });
```

**Response** `200 OK` with the group, as from [Get a group](https://docs.vaultpanel.net/api-reference/server-groups#get-a-group).

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such group. |
| 409 | `GROUP_EXISTS` | Another group has this name. |
| 422 | `VALIDATION_ERROR` | No fields, an invalid field, or a server that was not found. |

## Delete a group

`DELETE /api/v1/server-groups/:id` — Permission: servers.manage — Token scope: servers

Deletes the group only. Its servers and past bulk actions stay.

**Example request**

**cURL**

```bash
curl -X DELETE https://panel.example.com/api/v1/server-groups/c2d4e6f8-1a3b-4c5d-9e7f-2b4d6f8a0c1e \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
await panel.servers.groups.remove(groupId);
```

**Response** `200 OK` with `data: null`, message `Group deleted. Its servers were not changed.`

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such group. |

## Bulk actions

A bulk action runs one operation on up to 200 servers. Each server's part is an ordinary [job](https://docs.vaultpanel.net/api-reference/jobs) linked back to the action.

| Operation | What it does | Default mode | Checked after the job |
| --- | --- | --- | --- |
| `SERVICE_RESTART` | Restart the same systemd service on every server (`params.service`) | `parallel` | No |
| `SERVICE_START` | Start a stopped service (`params.service`) | `parallel` | No |
| `SERVICE_STATUS` | Read a service's state (`params.service`) | `parallel` | No |
| `SECURITY_UPDATES_INSTALL` | Install waiting security updates with unattended-upgrades | `rolling` | No |
| `AGENT_UPDATE` | Install the agent version this panel serves (the panel fills in the version and checksum) | `parallel` | The new version must be reported, within 3 minutes |
| `SERVER_REBOOT` | Restart the servers | `rolling` | A newer boot time must be reported, within 10 minutes |

**Modes.** `parallel` starts every server at once. `rolling` runs one server at a time: each must finish (and pass its check) before the next starts, and with `stopOnFailure` a failure stops the rest.

**Skipped servers.** Servers that are offline, have no agent, run an agent that cannot do the operation, or (for agent updates) are already current are `skipped` with the reason. If no server can run it, the action is refused with `409 NOTHING_TO_RUN`.

**The panel's own server** (`isLocal`) always runs last. For `SERVER_REBOOT` it also waits until every other server is done, even in `parallel` mode, and its reboot is given 24 hours to be confirmed, since the panel is down until it is started again.

A target goes `waiting`, then `running`, then `succeeded` or `failed`; reboots and agent updates pass through `verifying` while the panel waits for their check. The action is `running` until every target is final, then `succeeded`, `failed` or `cancelled`.

## List bulk actions

`GET /api/v1/bulk-actions` — Permission: jobs.read — Token scope: read

Bulk actions, newest first, with counts per target status. Supports the [list parameters](https://docs.vaultpanel.net/api-reference#lists-and-pagination).

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | No | `running`, `succeeded`, `failed` or `cancelled`. |
| `groupId` | string | No | Actions started on one group. |

**Example request**

**cURL**

```bash
curl "https://panel.example.com/api/v1/bulk-actions?status=running" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.bulkActions.list({ status: 'running' });
```

**Response** `200 OK`: `{ items: [action], pagination }`, each action as below without `targets`.

## Start a bulk action

`POST /api/v1/bulk-actions` — Permission: servers.bulk — Token scope: servers

Starts an operation on a list of servers or on every server of a group. You need `servers.bulk` and the operation's own permission (for example `servers.reboot`).

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | Yes | One of the operations above. |
| `params` | object | No | The operation's parameters, such as `{ "service": "nginx" }`. |
| `serverIds` | string[] | One of the two | Up to 200 servers. |
| `groupId` | string | One of the two | Every server in this group. |
| `mode` | string | No | `parallel` or `rolling`. Defaults to the operation's default. |
| `stopOnFailure` | boolean | No | For `rolling` mode: stop at the first failure. Default `true`. |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/bulk-actions \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" -H "Content-Type: application/json" \
  -d '{"type":"SECURITY_UPDATES_INSTALL","groupId":"c2d4e6f8-1a3b-4c5d-9e7f-2b4d6f8a0c1e","mode":"rolling"}'
```

**JavaScript**

```js
const action = await panel.bulkActions.create({
  type: 'SERVICE_RESTART',
  params: { service: 'php8.3-fpm' },
  groupId,
});
```

**Response** `202 Accepted`

```json
{
  "success": true,
  "data": {
    "id": "e9f8d7c6-5b4a-4392-8170-6f5e4d3c2b1a",
    "type": "SECURITY_UPDATES_INSTALL",
    "label": "Install security updates",
    "params": {},
    "mode": "rolling",
    "stopOnFailure": true,
    "status": "running",
    "group": { "id": "c2d4e6f8-1a3b-4c5d-9e7f-2b4d6f8a0c1e", "name": "Production" },
    "requestedBy": { "id": "3c9f0a52-7d1e-4b8a-9f3e-2a6d5c4b1e07", "email": "ada@example.com" },
    "counts": { "total": 3, "waiting": 2, "running": 1, "verifying": 0, "succeeded": 0, "failed": 0, "skipped": 0, "cancelled": 0 },
    "cancelledAt": null,
    "createdAt": "2026-11-10T11:20:00.000Z",
    "finishedAt": null,
    "targets": [
      {
        "id": "f1e2d3c4-…",
        "serverId": "1f6a3c2e-5b4d-4e7f-9a8b-0c1d2e3f4a5b",
        "serverName": "web-1",
        "position": 0,
        "status": "running",
        "message": null,
        "jobId": "a7b8c9d0-…",
        "jobStatus": "running",
        "isLocal": false,
        "verifyUntil": null,
        "startedAt": "2026-11-10T11:20:00.000Z",
        "finishedAt": null
      }
    ]
  },
  "message": "Bulk action started",
  "requestId": "…"
}
```

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 403 | `FORBIDDEN` | You lack `servers.bulk` or the operation's permission. |
| 404 | `NOT_FOUND` | The group was not found. |
| 409 | `GROUP_EMPTY` | The group has no servers. |
| 409 | `NOTHING_TO_RUN` | No server can run it. `details.servers` lists each server with its reason. |
| 422 | `VALIDATION_ERROR` | Not exactly one of `serverIds` and `groupId`, an unknown `type`, invalid `params`, a server that was not found, or more than 200 servers. |

## Get a bulk action

`GET /api/v1/bulk-actions/:id` — Permission: jobs.read — Token scope: read

The action with one target per server, in the order they run.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/bulk-actions/e9f8d7c6-5b4a-4392-8170-6f5e4d3c2b1a \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const action = await panel.bulkActions.get(actionId);
```

**Response** `200 OK` with the action, as from [Start a bulk action](https://docs.vaultpanel.net/api-reference/server-groups#start-a-bulk-action).

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such bulk action. |

## Cancel a bulk action

`POST /api/v1/bulk-actions/:id/cancel` — Permission: servers.bulk — Token scope: servers

Cancels the servers that have not started yet, including jobs still waiting for their agent. Anything already running on a server finishes.

**Example request**

**cURL**

```bash
curl -X POST https://panel.example.com/api/v1/bulk-actions/e9f8d7c6-5b4a-4392-8170-6f5e4d3c2b1a/cancel \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const action = await panel.bulkActions.cancel(actionId);
```

**Response** `200 OK` with the action, message `Servers that had not started were cancelled`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such bulk action. |
| 409 | `NOT_RUNNING` | The action has already finished. |
