Notifications
A notification is created when a batch ends in a state that needs attention. The API reads them; escalating, archiving and handling stay in the dashboard.
List the project's notifications
endpoint
GET /api/v1/projects/{project_id}/notificationsThe project's notifications, every environment, newest first, as a list of notification objects. Minimum key role: Participant.
| Parameter | Value |
|---|---|
status | OPEN, ESCALATED or ARCHIVED: only the notifications in this status. Default: all. |
since | Only the notifications created at or after this moment: a date, 2026-11-05, read as midnight UTC, or a timestamp with its zone, 2026-11-05T09:00:00Z. |
limit | How many items, from 1 to 100. Default 20. |
cursor | The next_cursor of the page, to read the page after it. |
To follow what happens in a project, keep the created_at of the newest notification you have read, and ask for the ones since then.
List an environment's notifications
endpoint
GET /api/v1/projects/{project_id}/environments/{environment_id}/notificationsThe same, for one environment. Takes the same parameters. Minimum key role: Participant.
Read a notification
endpoint
GET /api/v1/projects/{project_id}/notifications/{notification_id}One notification. Minimum key role: Participant.
The notification object
notification
{
"object": "notification",
"id": "00000000-0000-0000-0000-000000000009",
"environment_id": "00000000-0000-0000-0000-000000000001",
"title": "Diff batch failed",
"status": "OPEN",
"severity": "FAILURE",
"origin": {
"type": "DIFF_BATCH",
"capture_batch_id": null,
"diff_batch_id": "00000000-0000-0000-0000-000000000004"
},
"handled_at": null,
"escalated_at": null,
"archived_at": null,
"created_at": "2026-11-06T10:03:40.2+00:00",
"updated_at": "2026-11-06T10:03:40.2+00:00"
}| Field | Type | Value |
|---|---|---|
environment_id | uuid string | Where it happened. |
title | string | What happened, in a few words: Diff batch failed, Capture batch errored, … |
status | string | OPEN, ESCALATED or ARCHIVED — see status lifecycle. |
severity | string | FAILURE when the batch ended in Error, or the diff's verdict is Fail. WARNING for the other outcomes that create a notification: a capture batch with pages that failed (Warning), a diff whose verdict is Warn or Skipped, a diff that was Cancelled. A batch that ends well creates no notification — see how notifications are created. |
origin.type | string | CAPTURE_BATCH or DIFF_BATCH: the kind of batch that raised it. |
origin.capture_batch_id | uuid string | null | The capture batch, when it is one; null otherwise. |
origin.diff_batch_id | uuid string | null | The diff batch, when it is one; null otherwise. |
handled_at | timestamp | null | Since when someone has it in hand; null while nobody has. |
escalated_at | timestamp | null | When it was escalated; null if it never was, or was set back to Open. |
archived_at | timestamp | null | When it was archived; null when it is not. |
The object says when, never who: the people who escalated, archived or handled it are on its page in the dashboard. A diff's verdict is on its diff batch.