# List recent out-of-bed notifications

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

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

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

Lists the newest active out-of-bed notifications for your project. Use it for an out-of-bed notification bell.

**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]

- Out-of-bed is evaluated by Signals; Ovok serves one row per episode from Signals. Medical notifications are not here: read `GET /v1/slim/notifications/recent/medical` for those, so one event is never counted by both bells.
- Returns at most `count` rows, newest first by event time.
- Rows come from Signals episodes. The response has `warm: true` and `source: "signals"`.
- `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.
- `total` counts active out-of-bed episodes, capped at 1,000.
- The row id is the Signals episode id. Use it with `PATCH /v1/slim/notifications/{id}/ack`; episode notes use `/v1/slim/notifications/oob/{id}/notes`.
- An episode that has ended but has not been acknowledged stays active, and so stays in this bell, until someone acknowledges it with `PATCH /v1/slim/notifications/{id}/ack`. Its `episodeEndedAt` is set.
- One in-bed reading ends an absence and clears its acknowledgement silence. The next absent reading starts a new absence with its own start and limit, whether or not the previous one was acknowledged. See [How an episode behaves](/signals/connected-ovok#how-an-episode-behaves).
- Signals reads wait up to 5 seconds. If Signals does not answer, the route returns `503 signals_unavailable` ([`signals_unavailable`](/errors/signals-unavailable)) with `retryAfterSec` and `Retry-After`. The server can also shed a read with `503 live_reads_over_capacity` ([`live_reads_over_capacity`](/errors/live-reads-over-capacity)).

## Example [#example]

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

## Successful response [#successful-response]

`200` — Recent out-of-bed notifications retrieved successfully.

```json
{
  "recent": [
    {
      "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
    },
    {
      "commId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b14",
      "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": 2410,
        "level": "high"
      },
      "authoredOn": "2026-10-08T22:05:00.000Z",
      "alertCount": 7,
      "occurrenceDateTime": "2026-10-08T22:50:00.000Z",
      "episodeEndedAt": "2026-10-08T22:58:00.000Z",
      "effectiveTimestamp": "2026-10-08T22:05:00.000Z",
      "latestObservationTimestamp": "2026-10-08T22:50:00.000Z",
      "alarm": null,
      "noteCount": null
    }
  ],
  "total": 2,
  "warm": true,
  "source": "signals"
}
```

| 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 out-of-bed episodes counted, clamped to 1,000. |
| `warm` | `true` | Always `true` on this route. |
| `source` | `"signals"` | Always `signals`: the rows come from Signals episodes. |

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 out-of-bed episode's Signals id. Use it to acknowledge the notification with `PATCH /v1/slim/notifications/{id}/ack` and for `/v1/slim/notifications/oob/{id}/notes`. |
| `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"` | The notification type. Always `outOfBed` on this route. |
| `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` | `null` | Always `null` on this route; Signals owns the episode 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) | Signals did not answer within 5 seconds (`error: "signals_unavailable"` ([`signals_unavailable`](/errors/signals-unavailable))), or the server shed the read (`error: "live_reads_over_capacity"` ([`live_reads_over_capacity`](/errors/live-reads-over-capacity))). The body carries `retryAfterSec` and the `Retry-After` header carries the same delay in seconds. Retry after it. |
