---
title: Notifications
description: GET /v1/notifications — the alerting delivery history — every notification attempt with its channel, delivery status, severity, incident and monitor.
canonical: https://watchfor.io/docs/api/notifications
---

# Notifications

GET /v1/notifications — the alerting delivery history — every notification attempt with its channel, delivery status, severity, incident and monitor.

| Method | Path | Scope | operationId |
| --- | --- | --- | --- |
| GET | `/v1/notifications` | read | `listNotifications` |

The delivery log behind the dashboard's
[Alerting history](/docs/notifications/history): one row per notification
attempt. It answers "did the Slack alert actually go out?", "which
deliveries are failing?" and "who was paged for this incident?".
Notifications are written by the alerting pipeline; the endpoint is
read-only.

The notification object:

```json
{
  "id": 88213,
  "object": "notification",
  "status": "sent",
  "channel": { "id": 12, "type": "slack", "name": "#ops-alerts" },
  "oncall_page": false,
  "error": null,
  "severity": "critical",
  "incident": { "id": 19351, "status": "firing", "message": "Received an unexpected HTTP status code (expected: 2xx, 3xx)" },
  "monitor": { "id": "0b0f6a41-…", "name": "Marketing site" },
  "created_at": "2026-08-24T10:15:03.000Z"
}
```

| Field | Meaning |
| --- | --- |
| `status` | `sent`, `failed` or `silenced` (suppressed by a maintenance window or silence) |
| `channel` | The notification channel used — `type` such as `email`, `slack`, `discord`, `telegram`, `webhook`, `pagerduty`; `id` and `name` are `null` when the delivery did not go through a configured channel (personal on-call pages) or the channel has since been deleted |
| `oncall_page` | `true` when this was a personal page to whoever was on call (escalation policy), not a channel delivery |
| `error` | Delivery error message when `status` is `failed`, otherwise `null` |
| `severity` | Incident severity at send time (`critical` or `warning`) |
| `incident` | Id, current status and humanized message of the incident that triggered it |
| `monitor` | The monitor, or `null` if it has since been deleted |

## List notifications

`GET /v1/notifications` — newest first, cursor-paginated.

| Query | Meaning |
| --- | --- |
| `status` | `sent`, `failed` or `silenced` |
| `channel_type` | e.g. `telegram`, `slack`, `email`, `webhook`, `pagerduty` |
| `monitor_id` | Only this monitor's notifications (unknown id → `404`) |
| `incident_id` | Only this incident's notifications (integer) |
| `since` / `until` | ISO 8601 bounds on `created_at` |
| `limit` | 1–100, default 50 |
| `cursor` | The previous page's `next_cursor` |

```bash
curl "https://watchfor.io/api/v1/notifications?status=failed&since=2026-08-24T00:00:00Z" \
  -H "Authorization: Bearer wf_live_YOUR_KEY"
```

```json
{
  "object": "list",
  "data": [ { "id": 88213, "object": "notification", "…": "…" } ],
  "total": 3,
  "has_more": false,
  "next_cursor": null
}
```

`total` is the count of rows matching the filters, independent of
pagination.

## Typical uses

- **Delivery audit** — `?status=failed` in a daily job to catch a revoked
  Slack webhook or a bounced address before the next real incident.
- **Incident timeline** — `?incident_id=19351` shows every channel and
  on-call page for one incident, in order.
- **Channel health** — `?channel_type=pagerduty&since=…` to confirm an
  integration is live after changing it.

Channels themselves (creating a Slack or Telegram channel, routing rules)
are managed in the dashboard — see [Notifications](/docs/notifications).
Also available as the MCP tool `list_notifications`.

---

Canonical page: https://watchfor.io/docs/api/notifications · All docs: https://watchfor.io/docs · Site guide: https://watchfor.io/llms.txt