# List recent notifications

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

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

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

Lists the newest active notifications stored as CommunicationRequests for your project, of every type (such as out-of-bed, device alarms and attention presses). Use it for a notification bell. For filtered or paged history, use the out-of-bed and alarm feeds.

**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` and `CommunicationRequest:search` (admins and super admins skip this check).
**Scope:** The caller's project (from the token).

## Request [#request]

### Query parameters [#query-parameters]

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `count` | `integer` | No | The maximum number of rows to return. Minimum 1, maximum 50, default 20. |

## Behaviour [#behaviour]

- Returns at most `count` rows, newest first by event time.
- Warm responses use the notification projection (`warm` is `true`, `source` is `"redis"`). Cold responses read current notifications from the FHIR server (`warm` is `false`, `source` is `"fhirStore"`) and start loading the projection in the background, so a later call can be warm.
- The FHIR search returns `active` notifications updated within the last year.
- `total` counts active notifications up to the configured result cap (1,000 by default). Counts from a cold read are estimates.
- `locationName` is the room's current name, so a renamed room shows its new name on every row. If the caller cannot read the Location, or the lookup takes more than 2 seconds, a row keeps the name it was raised with.
- Rows whose notification type cannot be resolved are left out.
- Medical notifications (heart rate, respiratory rate and other vitals) are decided by Signals and served by `GET /v1/slim/notifications/recent/medical`. To show one type only, use `GET /v1/slim/notifications/recent/oob` or `GET /v1/slim/notifications/recent/alarms`.
- Only a cold read can be shed under load, with a 503 and a `Retry-After` header. A warm read is never shed.

## Example [#example]

```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/recent?count=20' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"
```

## Successful response [#successful-response]

`200` — Recent notifications retrieved successfully.

```json
{
  "recent": [
    {
      "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": null
    },
    {
      "commId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b11",
      "patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b12",
      "patientName": "demo-resident",
      "deviceId": "Demo/100AA01",
      "deviceName": "Demo/100AA01",
      "locationId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b13",
      "locationName": "Room 101",
      "color": "#E5254B",
      "trigger": "above",
      "type": "outOfBed",
      "status": "active",
      "details": {
        "threshold": 1800,
        "value": 1925,
        "level": "high"
      },
      "authoredOn": "2026-10-09T01:12:00.000Z",
      "alertCount": 4,
      "occurrenceDateTime": "2026-10-09T02:18:00.000Z",
      "effectiveTimestamp": "2026-10-09T01:12:00.000Z",
      "latestObservationTimestamp": "2026-10-09T02:18:00.000Z",
      "alarm": null,
      "noteCount": null
    }
  ],
  "total": 2,
  "warm": true,
  "source": "redis"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `recent` | `object[]` | The notifications, newest first by event time. Each element is a row, described below. |
| `total` | `integer` | The number of active notifications the source knows about, clamped to 1,000 (the list result cap). An estimate on a cold read. |
| `warm` | `boolean` | `true` when the warm projection served the request, `false` for a cold read. |
| `source` | `"redis"` \| `"fhirStore"` | `"redis"` when the warm projection served the request, `"fhirStore"` when the rows were read from the FHIR server. |

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 |
| --- | --- | --- |
| `recent[].commId` | `string` | The CommunicationRequest id, or for an out-of-bed row the Signals episode id. Use it to acknowledge the notification with `PATCH /v1/slim/notifications/{id}/ack`. |
| `recent[].patientId` | `string (uuid)` | The resident's Patient id. Omitted when the notification has no resident. |
| `recent[].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. |
| `recent[].deviceId` | `string` | The device identifier stamped on the notification: usually the device's name or serial, for example `Demo/100AA01`. Omitted when unknown. |
| `recent[].deviceName` | `string` | The device's display name. Omitted when unknown. |
| `recent[].locationId` | `string (uuid)` | The room's Location id. Omitted when the notification has no room. |
| `recent[].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. |
| `recent[].color` | `string` | Display colour of the alert as a hex string, for example `#E5254B`. Omitted when absent. |
| `recent[].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. |
| `recent[].type` | `"outOfBed"` \| `"deviceAlarm"` \| `"attention"` \| `"hr"` \| `"br"` | The notification type. `outOfBed` is a bed exit. `deviceAlarm` and `attention` are alarms and attention presses decided by the sending system. `hr` and `br` are legacy types: new heart rate and respiratory rate alerts are medical notifications, served by the medical routes. |
| `recent[].status` | `"active"` | Always `active` on this route: only active notifications are listed. |
| `recent[].details` | `object` | Measurement details. Always present; every field inside is omitted when unknown. |
| `recent[].details.threshold` | `number` | The limit that was crossed. For out-of-bed, in seconds. |
| `recent[].details.value` | `number` | The measured value that crossed the limit. For out-of-bed, a duration in seconds. |
| `recent[].details.level` | `string` | Severity label: `high` or `low` for a limit breach, `red`, `yellow` or `attention` for an alarm. |
| `recent[].authoredOn` | `string (ISO 8601 date-time)` | When the notification was created, in UTC. Falls back to its last update time. |
| `recent[].alertCount` | `integer` | How many alerts the notification has absorbed (at least 1). Omitted when not recorded. |
| `recent[].occurrenceDateTime` | `string (ISO 8601 date-time)` | When the latest event on the notification happened, in UTC. It advances while an episode continues. |
| `recent[].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. |
| `recent[].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`. |
| `recent[].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`. |
| `recent[].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. |
| `recent[].alarm.episodeId` | `string` | The sender's own id for the alarm, so it can match an acknowledgement to its record. |
| `recent[].alarm.severity` | `"RED"` \| `"YELLOW"` \| `"ATTENTION"` | The severity as the sender coded it. `ATTENTION` is an attention press. |
| `recent[].alarm.type` | `string` | The sender's alarm type, for example `DEVICE_ALARM`. |
| `recent[].alarm.text` | `string \| null` | The sender's alarm text, or `null` when it sent none. |
| `recent[].noteCount` | `integer \| null` | Always `null` on this route: bells do not count notes. |

## 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` or `CommunicationRequest:search`, your session has no project, or you cannot access the project. |
| [`422`](/errors/validation-failed) | A query parameter fails validation. |
| [`503`](/errors/service-unavailable) | A cold 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) | The FHIR search on the fallback path timed out. |
