# List alarm notifications

Canonical page: https://docs.ovok.com/slim-apis/notifications/list-alarm-notifications

| Method | Path |
| --- | --- |
| `GET` | `/v1/slim/notifications/alarms` |

[Authentication](/authentication) · [Access policies](/access-policies)

Lists your project's device alarms and attention presses, filtered and paged. These are decided by the sending system; Ovok stores them as CommunicationRequests and forwards them.

**Auth:** Bearer token. The caller must be a practitioner, an admin, a super admin, or hold the "System Owner" access policy. The access policy must grant `CommunicationRequest:read`, `CommunicationRequest:search` and `Observation:read` (admins and super admins skip this check).
**Scope:** The caller's project (from the token). The `project` query parameter is accepted but ignored.

## Request [#request]

### Query parameters [#query-parameters]

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `string` | No | Comma-separated notification types: `deviceAlarm`, `attention`, or both. Both when omitted. An unknown entry, or an empty list, fails validation. |
| `severity` | `string` | No | Comma-separated severities, as the sender coded the alarm: `RED`, `YELLOW`, `ATTENTION` (case-sensitive). Every severity when omitted. |
| `sort` | `"newest"` \| `"oldest"` | No | Order by event time. Default `newest`. |
| `status` | `"active"` \| `"completed"` \| `"cancelled"` \| `"draft"` \| `"on-hold"` \| `"revoked"` \| `"unknown"` \| `"entered-in-error"` | No | The notification status to list. Default `active`. An acknowledged alarm is `completed`. |
| `patient` | `string` | No | Only this resident's alarms. A Patient id, or `Patient/{id}`. |
| `device` | `string` | No | Only this device's alarms. A Device id, `Device/{id}`, or the device's identifier value (for example `Demo/200BB02`). A Device id that does not exist returns an empty page, not an unfiltered one. |
| `startDate` | `string (ISO 8601 date-time)` | No | Inclusive lower bound, a UTC instant ending in `Z`, used exactly as sent. Defaults to one year back for `status=active` and 30 days back otherwise. |
| `endDate` | `string (ISO 8601 date-time)` | No | Inclusive upper bound, a UTC instant ending in `Z`, used exactly as sent. No default. Must not be before `startDate`. |
| `page` | `integer` | No | The zero-based page number. Minimum 0, default 0. |
| `count` | `integer` | No | The page size. Minimum 1, maximum 100, default 25. |
| `project` | `string` | No | Accepted and ignored. The project always comes from the token. |

## Behaviour [#behaviour]

- One row per alarm episode. Each row's `alarm` carries the sender's own alarm id (`episodeId`), its severity, type and text, so the sender can match an acknowledgement to its own record.
- `type`: `deviceAlarm`, `attention`, or both comma separated. Both when omitted.
- `severity`: `RED`, `YELLOW`, `ATTENTION`, comma separated, as the sender coded the alarm. Every severity when omitted.
- `status` defaults to `active`; an acknowledged alarm is `completed`.
- `sort`: `newest` (default) or `oldest`, by event time (`occurrenceDateTime`, then `authoredOn`, then id).
- `patient`, `device`, `startDate`, `endDate`, `page`, `count`, `total` and `truncated` work as on `GET /v1/slim/notifications/oob`: `count` is 1 to 100 (default 25), dates are inclusive UTC instants, and the list pages through at most the first 1,000 results (server-configurable).
- `noteCount` counts the notes left on each row. It is `null` for a row whose count could not be established.
- Acknowledge a row with `PATCH /v1/slim/notifications/{id}/ack`.
- Out-of-bed is on `GET /v1/slim/notifications/oob`; vital-sign alerts, decided by Signals, are on `GET /v1/slim/notifications/medical`.
- Under load the read can be shed with a 503 and a `Retry-After` header.

## Example [#example]

```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/alarms?severity=YELLOW,ATTENTION&sort=newest' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"
```

## Successful response [#successful-response]

`200` — Alarm notifications retrieved successfully.

```json
{
  "total": 2,
  "page": 0,
  "count": 25,
  "truncated": null,
  "resources": [
    {
      "commId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b32",
      "patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b62",
      "patientName": "demo-resident-2",
      "deviceId": "Demo/200BB02",
      "deviceName": "Demo/200BB02",
      "locationId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b63",
      "locationName": "Room 102",
      "color": "#E5254B",
      "type": "attention",
      "status": "active",
      "details": {
        "level": "attention"
      },
      "authoredOn": "2026-10-09T02:26:00.000Z",
      "alertCount": 1,
      "occurrenceDateTime": "2026-10-09T02:26:00.000Z",
      "effectiveTimestamp": "2026-10-09T02:26:00.000Z",
      "latestObservationTimestamp": "2026-10-09T02:26:00.000Z",
      "alarm": {
        "episodeId": "evt_2043",
        "severity": "ATTENTION",
        "type": "DEVICE_ALARM",
        "text": null
      },
      "noteCount": 2
    },
    {
      "commId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b31",
      "patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b62",
      "patientName": "demo-resident-2",
      "deviceId": "Demo/200BB02",
      "deviceName": "Demo/200BB02",
      "locationId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b63",
      "locationName": "Room 102",
      "color": "#F5A524",
      "type": "deviceAlarm",
      "status": "active",
      "details": {
        "level": "yellow"
      },
      "authoredOn": "2026-10-09T02:20:00.000Z",
      "alertCount": 1,
      "occurrenceDateTime": "2026-10-09T02:20:00.000Z",
      "effectiveTimestamp": "2026-10-09T02:20:00.000Z",
      "latestObservationTimestamp": "2026-10-09T02:20:00.000Z",
      "alarm": {
        "episodeId": "evt_2041",
        "severity": "YELLOW",
        "type": "DEVICE_ALARM",
        "text": "Check sensor"
      },
      "noteCount": 0
    }
  ]
}
```

| Field | Type | Description |
| --- | --- | --- |
| `total` | `integer` | The exact number of notifications that match the filter, the same on every page, clamped to 1,000 (the list result cap). It counts matching notifications, so it is an upper bound on the rows you can page through. It reads `0` if the count lookup fails; the rows are unaffected. |
| `page` | `integer` | The page number you asked for. |
| `count` | `integer` | The page size you asked for. |
| `truncated` | `object \| null` | `null` when nothing was withheld. Otherwise the server stopped looking, and this says why. |
| `truncated.reason` | `"result-cap"` \| `"scan-budget"` | `result-cap`: more rows exist beyond the 1,000-result cap. `scan-budget`: the per-request scan limit ran out before the page filled. |
| `truncated.limit` | `integer` | The cap or scan limit that was reached. |
| `resources` | `object[]` | The page of rows, newest first by event time unless `sort` says otherwise. Each element is a row, described below. |

Each row is one notification. A field described as omitted is left out of the JSON when it has no value; it is not sent as `null`. `details`, `alarm` and `noteCount` are always present.

| Field | Type | Description |
| --- | --- | --- |
| `resources[].commId` | `string (uuid)` | The notification id. Use it to acknowledge the notification with `PATCH /v1/slim/notifications/{id}/ack`. |
| `resources[].patientId` | `string (uuid)` | The resident's Patient id. Omitted when the notification has no resident. |
| `resources[].patientName` | `string` | The resident's label (their Resident ID): the Patient's nickname, otherwise its official given name, otherwise the name stored on the notification. Omitted when no usable name is available. |
| `resources[].deviceId` | `string` | The device identifier stamped on the notification: usually the device's name or serial, for example `Demo/200BB02`. Omitted when unknown. |
| `resources[].deviceName` | `string` | The device's display name. Omitted when unknown. |
| `resources[].locationId` | `string (uuid)` | The room's Location id. Omitted when the notification has no room. |
| `resources[].locationName` | `string` | The room's current name, read from the Location. A row keeps the name it was raised with when the Location cannot be read. Omitted when no name is available; it is never a raw id. |
| `resources[].color` | `string` | Display colour of the alert as a hex string, for example `#E5254B`. Omitted when absent. |
| `resources[].trigger` | `"above"` \| `"below"` | Whether the value went above the upper limit or below the lower limit. Omitted when the notification has no direction, such as an alarm. |
| `resources[].type` | `"deviceAlarm"` \| `"attention"` | The notification type: `deviceAlarm` for a device alarm, `attention` for an attention press. |
| `resources[].status` | `"active"` \| `"completed"` \| `"on-hold"` \| `"draft"` \| `"revoked"` \| `"entered-in-error"` \| `"unknown"` | The notification's status. `active` until someone acknowledges it, then `completed`. The other values are standard FHIR request statuses. |
| `resources[].details` | `object` | Measurement details. Always present; every field inside is omitted when unknown. |
| `resources[].details.threshold` | `number` | The limit that was crossed. For out-of-bed, in seconds. |
| `resources[].details.value` | `number` | The measured value that crossed the limit. For out-of-bed, a duration in seconds. |
| `resources[].details.level` | `string` | Severity label: `high` or `low` for a limit breach, `red`, `yellow` or `attention` for an alarm. |
| `resources[].authoredOn` | `string (ISO 8601 date-time)` | When the notification was created, in UTC. Falls back to its last update time. |
| `resources[].alertCount` | `integer` | How many alerts the notification has absorbed (at least 1). Omitted when not recorded. |
| `resources[].occurrenceDateTime` | `string (ISO 8601 date-time)` | When the latest event on the notification happened, in UTC. It advances while an episode continues. |
| `resources[].episodeEndedAt` | `string (ISO 8601 date-time)` | Set when an out-of-bed episode has ended. The notification stays `active` until someone acknowledges it. Omitted while the episode runs and on other types. |
| `resources[].effectiveTimestamp` | `string (ISO 8601 date-time)` | The stable start of the episode: for out-of-bed, the moment the resident left the bed. It does not change as `occurrenceDateTime` advances. Omitted on older notifications; fall back to `authoredOn`. |
| `resources[].latestObservationTimestamp` | `string (ISO 8601 date-time)` | When the newest reading behind the notification was taken. Omitted on older notifications; fall back to `effectiveTimestamp`, then `authoredOn`. |
| `resources[].alarm` | `object \| null` | The sender's alarm, for `deviceAlarm` and `attention` notifications. `null` for every other type, and when the sender's alarm record is incomplete. |
| `resources[].alarm.episodeId` | `string` | The sender's own id for the alarm, so it can match an acknowledgement to its record. |
| `resources[].alarm.severity` | `"RED"` \| `"YELLOW"` \| `"ATTENTION"` | The severity as the sender coded it. `ATTENTION` is an attention press. |
| `resources[].alarm.type` | `string` | The sender's alarm type, for example `DEVICE_ALARM`. |
| `resources[].alarm.text` | `string \| null` | The sender's alarm text, or `null` when it sent none. |
| `resources[].noteCount` | `integer \| null` | The number of notes on this notification. `null` when the count could not be established. |

## Errors [#errors]

| Status | Meaning |
| --- | --- |
| [`401`](/errors/unauthenticated) | Bearer token is missing, invalid or expired. |
| [`403`](/errors/forbidden) | You are not a practitioner, admin or System Owner, you lack `CommunicationRequest:read`, `CommunicationRequest:search` or `Observation:read`, your session has no project, you cannot access the project, or the `device` filter names a Device you cannot read. |
| [`422`](/errors/validation-failed) | A query parameter fails validation, for example a `count` outside 1 to 100, a negative `page`, an unknown `type`, `severity` or `sort` value, a `startDate` or `endDate` that is not a UTC instant, or a `startDate` after `endDate`. |
| [`503`](/errors/service-unavailable) | The read was shed because the server is at capacity. The body carries `error` set to [`live_reads_over_capacity`](/errors/live-reads-over-capacity) and `retryAfterSec`, and the `Retry-After` header carries the same delay in seconds. Retry after it. |
| [`504`](/errors/upstream-timeout) | A FHIR notification search timed out. |
