# Monitoring and alerts

URL: https://docs.vaultpanel.net/api-reference/monitoring-and-alerts

> API reference for the fleet monitoring overview, services across servers, firing alerts, acknowledgements and alert rules.

Monitoring endpoints read what agents already report in their heartbeats: the latest metrics, a one-hour trend and the state of watched services on every server. Alert rules are evaluated by the panel's worker like Prometheus rules: when a rule's condition becomes true an event is `pending`, it becomes `firing` once the condition has held for the rule's `durationSeconds`, and `resolved` when it clears. A pending event whose condition clears is deleted.

For a single server's metric history, see [Servers](https://docs.vaultpanel.net/api-reference/servers). For the concepts and the panel pages, see [Monitoring and alerts](https://docs.vaultpanel.net/guides/servers/monitoring-and-alerts).

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v1/monitoring/overview` | [Get the fleet overview](https://docs.vaultpanel.net/api-reference/monitoring-and-alerts#get-the-fleet-overview) |
| GET | `/api/v1/monitoring/services` | [List services across servers](https://docs.vaultpanel.net/api-reference/monitoring-and-alerts#list-services-across-servers) |
| GET | `/api/v1/alerts/summary` | [Get the alert summary](https://docs.vaultpanel.net/api-reference/monitoring-and-alerts#get-the-alert-summary) |
| GET | `/api/v1/alerts/events` | [List alerts](https://docs.vaultpanel.net/api-reference/monitoring-and-alerts#list-alerts) |
| POST | `/api/v1/alerts/events/:id/acknowledge` | [Acknowledge an alert](https://docs.vaultpanel.net/api-reference/monitoring-and-alerts#acknowledge-an-alert) |
| GET | `/api/v1/alerts/rules` | [List alert rules](https://docs.vaultpanel.net/api-reference/monitoring-and-alerts#list-alert-rules) |
| POST | `/api/v1/alerts/rules` | [Create an alert rule](https://docs.vaultpanel.net/api-reference/monitoring-and-alerts#create-an-alert-rule) |
| PATCH | `/api/v1/alerts/rules/:id` | [Update an alert rule](https://docs.vaultpanel.net/api-reference/monitoring-and-alerts#update-an-alert-rule) |
| DELETE | `/api/v1/alerts/rules/:id` | [Delete an alert rule](https://docs.vaultpanel.net/api-reference/monitoring-and-alerts#delete-an-alert-rule) |

## Get the fleet overview

`GET /api/v1/monitoring/overview` — Permission: servers.read — Token scope: read

Returns every server with its latest metrics, its fullest filesystem, how many watched services have a problem (failed, or stopped although enabled at boot), a one-hour CPU and memory trend of up to 30 points, and its firing alerts by severity. `firingAlerts` is `null` when you lack `alerts.read`.

**Example request**

**cURL**

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

**JavaScript**

```js
const { items, totals } = await panel.monitoring.overview();
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c",
        "name": "web-1",
        "status": "online",
        "hostname": "web-1",
        "cpuCores": 4,
        "lastSeenAt": "2026-11-10T10:15:02.000Z",
        "latestMetrics": {
          "collectedAt": "2026-11-10T10:15:00.000Z",
          "cpuPercent": 12.4,
          "load": [0.42, 0.38, 0.35],
          "memoryUsedBytes": 1879048192,
          "memoryTotalBytes": 4294967296,
          "swapUsedBytes": 0,
          "swapTotalBytes": 1073741824,
          "diskUsedBytes": 21474836480,
          "diskTotalBytes": 85899345920,
          "netRxBytesPerSec": 10240,
          "netTxBytesPerSec": 20480,
          "processCount": 187,
          "uptimeSeconds": 864000
        },
        "fullestFilesystem": { "mount": "/", "percent": 25, "usedBytes": 21474836480, "totalBytes": 85899345920 },
        "services": { "total": 14, "problems": 0 },
        "trend": [{ "t": "2026-11-10T09:16:00.000Z", "cpu": 10.2, "memory": 43.1 }],
        "firingAlerts": { "warning": 0, "critical": 0 }
      }
    ],
    "totals": { "servers": 1, "byStatus": { "pending": 0, "online": 1, "offline": 0, "disabled": 0 } }
  },
  "message": "OK",
  "requestId": "…"
}
```

## List services across servers

`GET /api/v1/monitoring/services` — Permission: servers.read — Token scope: read

Returns every watched systemd service on every connected server, as the agents last reported them, with the server each one runs on.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `state` | string | No | `all` (default), `running` (active services only) or `problem` (failed, or stopped although enabled at boot). |
| `search` | string | No | Part of a service or server name, up to 100 characters. |

**Example request**

**cURL**

```bash
curl "https://panel.example.com/api/v1/monitoring/services?state=problem" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.monitoring.services({ state: 'problem' });
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "name": "nginx",
        "loadState": "loaded",
        "active": "failed",
        "sub": "failed",
        "enabled": "enabled",
        "description": "A high performance web server and a reverse proxy server",
        "problem": true,
        "server": { "id": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c", "name": "web-1", "status": "online", "lastSeenAt": "2026-11-10T10:15:02.000Z" }
      }
    ]
  },
  "message": "OK",
  "requestId": "…"
}
```

## Get the alert summary

`GET /api/v1/alerts/summary` — Permission: alerts.read — Token scope: read

Counts firing alerts, in total, not yet acknowledged and by severity. The panel's top bar uses it.

**Example request**

**cURL**

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

**JavaScript**

```js
const { firing, unacknowledged, bySeverity } = await panel.alerts.summary();
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": { "firing": 2, "unacknowledged": 1, "bySeverity": { "warning": 1, "critical": 1 } },
  "message": "OK",
  "requestId": "…"
}
```

## List alerts

`GET /api/v1/alerts/events` — Permission: alerts.read — Token scope: read

Returns alert events a page at a time, newest first.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string | No | `pending`, `firing`, `resolved`, or `open` (pending and firing together). |
| `serverId` | string (UUID) | No | Only alerts for this server. |
| `severity` | string | No | `warning` or `critical`. |
| `page`, `pageSize` | integer | No | Page from 1; 1 to 100 per page (default 25). |
| `sort`, `order` | string | No | `startedAt` (default) or `resolvedAt`; `desc` (default) or `asc`. |

**Example request**

**cURL**

```bash
curl "https://panel.example.com/api/v1/alerts/events?status=open" \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const { items } = await panel.alerts.events({ status: 'open' });
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "c0d1e2f3-…",
        "ruleId": "b7c8d9e0-…",
        "ruleName": "Disk almost full",
        "serverId": "9b2e7c1a-0d3f-4e8b-a6c5-7d8e9f0a1b2c",
        "serverName": "web-1",
        "metric": "disk_percent",
        "subject": "/",
        "severity": "critical",
        "status": "firing",
        "threshold": 90,
        "value": 93.4,
        "message": "Disk usage on / is 93% (threshold 90%)",
        "startedAt": "2026-11-10T09:50:00.000Z",
        "firedAt": "2026-11-10T09:55:00.000Z",
        "resolvedAt": null,
        "acknowledgedAt": null,
        "acknowledgedBy": null,
        "lastEvaluatedAt": "2026-11-10T10:15:00.000Z"
      }
    ],
    "pagination": { "page": 1, "pageSize": 25, "total": 1, "totalPages": 1 }
  },
  "message": "OK",
  "requestId": "…"
}
```

`subject` names what the alert is about when a rule covers several things: the filesystem for `disk_percent`, the service for `service_down`, the website's address for `website_down`.

## Acknowledge an alert

`POST /api/v1/alerts/events/:id/acknowledge` — Permission: alerts.acknowledge — Token scope: manage

Marks a firing alert as acknowledged by you, so others know someone is on it. It keeps firing until its condition clears.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/alerts/events/c0d1e2f3-a4b5-4c6d-8e7f-9a0b1c2d3e4f/acknowledge \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
const event = await panel.alerts.acknowledge(eventId);
```

**Response** `200 OK`: the alert event, with `acknowledgedAt` and `acknowledgedBy`; message `Alert acknowledged`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No alert with this id. |
| 409 | `ALERT_NOT_ACKNOWLEDGEABLE` | The alert is not firing, or was already acknowledged. |

## List alert rules

`GET /api/v1/alerts/rules` — Permission: alerts.read — Token scope: read

Returns every rule, oldest first, each with `firingCount`: how many of its alerts are firing now.

**Example request**

**cURL**

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

**JavaScript**

```js
const { items } = await panel.alerts.rules();
```

**Response** `200 OK`

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "b7c8d9e0-…",
        "name": "Disk almost full",
        "metric": "disk_percent",
        "threshold": 90,
        "durationSeconds": 300,
        "severity": "critical",
        "serverId": null,
        "serverName": null,
        "serviceName": null,
        "isEnabled": true,
        "createdAt": "2026-10-04T08:00:00.000Z",
        "updatedAt": "2026-10-04T08:00:00.000Z",
        "firingCount": 1
      }
    ]
  },
  "message": "OK",
  "requestId": "…"
}
```

## Create an alert rule

`POST /api/v1/alerts/rules` — Permission: alerts.manage — Token scope: manage

Creates a rule. A rule without `serverId` applies to every server.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | 1 to 100 characters. |
| `metric` | string | Yes | One of the metrics below. |
| `threshold` | number or null | Metric rules | Required for the metric kinds, in the metric's range; ignored for the others. |
| `durationSeconds` | integer | Yes | How long the condition must hold before the alert fires: 0 to 86400. |
| `severity` | string | Yes | `warning` or `critical`. |
| `serverId` | string (UUID) or null | No | One server, or every server when left out. |
| `serviceName` | string or null | No | `service_down` only: one systemd service to watch. Without it, every watched service is checked. |
| `isEnabled` | boolean | No | Default `true`. |

| `metric` | Kind | `threshold` |
| --- | --- | --- |
| `cpu_percent` | Metric | 1 to 100 (%) |
| `memory_percent` | Metric | 1 to 100 (%) |
| `disk_percent` | Metric, per filesystem | 1 to 100 (%) |
| `swap_percent` | Metric | 1 to 100 (%) |
| `load_per_core` | Metric | 0.1 to 100 |
| `server_offline` | The server stops reporting | None |
| `service_down` | A service is down | None |
| `website_down` | A website on the server fails the panel's [uptime checks](https://docs.vaultpanel.net/guides/websites/uptime-monitoring) (one alert per website) | None |
| `self_check_failed` | The server's [self-check](https://docs.vaultpanel.net/guides/servers/self-check) reports a failure | None |

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/alerts/rules \
  -X POST \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Disk almost full", "metric": "disk_percent", "threshold": 90, "durationSeconds": 300, "severity": "critical" }'
```

**JavaScript**

```js
const rule = await panel.alerts.createRule({
  name: 'Disk almost full',
  metric: 'disk_percent',
  threshold: 90,
  durationSeconds: 300,
  severity: 'critical',
});
```

**Response** `201 Created`: the rule, message `Alert rule created`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 422 | `VALIDATION_ERROR` | A missing or out-of-range threshold, `serviceName` on a rule that is not `service_down`, an unknown server, or another invalid field. |

## Update an alert rule

`PATCH /api/v1/alerts/rules/:id` — Permission: alerts.manage — Token scope: manage

Changes any of the rule's fields (the same fields as [Create an alert rule](https://docs.vaultpanel.net/api-reference/monitoring-and-alerts#create-an-alert-rule), all optional; send at least one). The merged rule is checked again. Changing `metric`, `threshold`, `serverId` or `serviceName`, or turning the rule off, resolves its open alerts, since they no longer mean the same thing.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/alerts/rules/b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e \
  -X PATCH \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "threshold": 85 }'
```

**JavaScript**

```js
const rule = await panel.alerts.updateRule(ruleId, { threshold: 85 });
```

**Response** `200 OK`: the rule, message `Alert rule updated`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No rule with this id. |
| 422 | `VALIDATION_ERROR` | No field given, or the merged rule is invalid. |

## Delete an alert rule

`DELETE /api/v1/alerts/rules/:id` — Permission: alerts.manage — Token scope: manage

Resolves the rule's open alerts and deletes it.

**Example request**

**cURL**

```bash
curl https://panel.example.com/api/v1/alerts/rules/b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e \
  -X DELETE \
  -H "Authorization: Bearer $VAULTPANEL_TOKEN"
```

**JavaScript**

```js
await panel.alerts.removeRule(ruleId);
```

**Response** `200 OK`: `data` is `null`, message `Alert rule deleted`.

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No rule with this id. |
