# List medical notifications

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

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

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

Lists your project's medical notifications (heart rate, respiratory rate and other vital-sign alerts), newest first, one page at a time. Medical episodes are decided by Signals; Ovok reads them from Signals, adds the resident context, and never re-derives a clinical value.

**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 `Patient:read`, `Device:read` and `Location:read` (admins and super admins skip this check).
**Scope:** The caller's project (from the token), applied on both sides: Signals filters on the resident's project stamp, and Ovok checks each resolved resident against your project.

## Request [#request]

### Query parameters [#query-parameters]

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | `"OPEN"` \| `"CLOSED"` | No | Only episodes in this state. Both when omitted. |
| `since` | `string (ISO 8601 date-time)` | No | Only episodes opened at or after this instant. A UTC instant ending in `Z`. |
| `acknowledged` | `string` | No | `true`, `1` or `yes` (any case) for acknowledged episodes only. Any other value, such as `false`, for unacknowledged only. Both when omitted. |
| `patient` | `string` | No | Only this resident's episodes: an Ovok `Patient.id`, the `carehub.patientId` a row returns. Maximum 64 characters. It does not widen the project scope. |
| `codes` | `string` | No | Only these vitals: LOINC codes, comma separated, at most 32, no spaces, for example `8867-4,9279-1`. `PI` is perfusion index. Signals applies the filter. Omit for every medical code. |
| `limit` | `integer` | No | The page size. Minimum 1, maximum 200, default 50. |
| `cursor` | `string` | No | The previous page's `nextCursor`, passed back unchanged. Opaque; maximum 500 characters. |

## Behaviour [#behaviour]

- One row per episode, not per reading: a run of readings outside the band is one episode. Its `closeReason` values are listed in [How an episode behaves](/signals/connected-ovok#how-an-episode-behaves).
- Each row has three blocks. `episode` is the Signals episode with its aggregates. `carehub` is the resident context Signals does not hold: resident, room and bed, device, zone. Its fields are `null` when the resident has no device assigned. `acknowledgement` is `null` until someone acknowledges the episode.
- Use `episode.id` with `GET /v1/slim/notifications/medical/{episodeId}` to get the full value history.
- `episode.firedBand` is the band the episode was judged under: the band Signals recorded when it fired, or else the band rebuilt from Signals' configuration history at the episode's trigger version. It is not the resident's current band, so editing a threshold does not change past rows. `min` and `max` are each nullable (a band can be one-sided). `firedBand` is `null` when the band cannot be established; that never fails the read.
- Filters: `status` (`OPEN` or `CLOSED`, both when omitted), `since` (episodes opened at or after this ISO 8601 instant), `acknowledged` (`true`, `1` or `yes` for acknowledged only; any other value for unacknowledged only; both when omitted).
- `patient` narrows the feed to one resident, by Ovok `Patient.id` (the `carehub.patientId` a row returns). It does not change the project scope. A resident who cannot be resolved, or who is in another project, answers 404 rather than an unfiltered page.
- `codes` narrows the feed to these LOINC codes, comma separated, at most 32 (for example `8867-4,9279-1`). Perfusion index is `PI`. Signals applies the filter. Out-of-bed is never in this feed. A malformed list fails validation.
- Paging: `limit` is 1 to 200 (default 50). Pass the previous page's `nextCursor` as `cursor`. Page until `nextCursor` is `null`, not until a short page arrives: rows whose resident cannot be resolved into your project are dropped after Signals counted them. Treat the cursor as opaque.
- `noteCount` counts the notes left on each episode. It is `null` for a row whose count could not be established.
- A resident with no Signals project stamp matches no project and does not appear.
- When the project's Signals tenant has episodic alerts switched off, the page is empty.
- Out-of-bed is served by `GET /v1/slim/notifications/oob`.
- Ovok waits up to 5 seconds for Signals. A `503 signals_unavailable` ([`signals_unavailable`](/errors/signals-unavailable)) means Signals did not answer in time; it is not an empty result. Retry after `retryAfterSec`. Under load the read can also be shed with a 503 ([`live_reads_over_capacity`](/errors/live-reads-over-capacity)).

## Example [#example]

```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/notifications/medical?status=OPEN&codes=8867-4,9279-1&limit=50' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"
```

## Successful response [#successful-response]

`200` — A page of medical notifications.

```json
{
  "items": [
    {
      "episode": {
        "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21",
        "patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b22",
        "code": "8867-4",
        "system": "http://loinc.org",
        "display": null,
        "status": "OPEN",
        "openedAt": "2026-10-09T07:40:12.000Z",
        "closedAt": null,
        "closeReason": null,
        "lastSampleAt": "2026-10-09T08:05:12.000Z",
        "durationMs": 1500000,
        "observationCount": 6,
        "firingCount": 6,
        "minValue": 118,
        "maxValue": 134,
        "avgValue": 125.5,
        "lastValue": 131,
        "peakValue": 134,
        "peakAt": "2026-10-09T07:55:12.000Z",
        "lastFiringValue": 131,
        "lastFiringAt": "2026-10-09T08:05:12.000Z",
        "lastObservationId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b41",
        "firedBand": {
          "min": 50,
          "max": 110,
          "triggerVersion": 2
        }
      },
      "carehub": {
        "patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b22",
        "patientName": "demo-resident",
        "locationId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b23",
        "locationName": "Room 101",
        "room": "101",
        "bed": "A",
        "floor": "1",
        "deviceId": "DEMO-0001",
        "deviceMedplumId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b24",
        "deviceName": "Demo Bed Sensor",
        "organizationId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b25",
        "organizationName": "Demo Care Home"
      },
      "acknowledgement": null,
      "noteCount": 0
    }
  ],
  "nextCursor": "c2FtcGxlLWN1cnNvcg"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `items` | `object[]` | The page of episodes, newest first. Each element is a row, described below. |
| `nextCursor` | `string \| null` | An opaque cursor for the next page, or `null` on the last page. Page until it is `null`, not until a short page arrives. |

Each row has three blocks (`episode`, `carehub`, `acknowledgement`) and a `noteCount`. A nullable field is always present, as `null` when it has no value.

| Field | Type | Description |
| --- | --- | --- |
| `items[].episode` | `object` | The Signals episode with its aggregates, passed through as Signals reported it. One episode is a run of readings outside the band. |
| `items[].episode.id` | `string` | The episode id. Use it with `GET /v1/slim/notifications/medical/{episodeId}` and `POST /v1/slim/notifications/medical/{episodeId}/ack`. |
| `items[].episode.patientId` | `string` | The resident's id at Signals. It equals `carehub.patientId` for residents created recently; use `carehub.patientId` with other Ovok routes. |
| `items[].episode.code` | `string` | The vital the episode is about: a LOINC code such as `8867-4` (heart rate) or `9279-1` (respiratory rate), or `PI` for perfusion index. |
| `items[].episode.system` | `string \| null` | The code system of `code`, for example `http://loinc.org`. |
| `items[].episode.display` | `string \| null` | Display text for `code`, when Signals has one. |
| `items[].episode.status` | `"OPEN"` \| `"CLOSED"` | Whether the episode is still running. |
| `items[].episode.openedAt` | `string (ISO 8601 date-time)` | When the episode opened. |
| `items[].episode.closedAt` | `string (ISO 8601 date-time) \| null` | When it closed. `null` while it is open. |
| `items[].episode.closeReason` | `"RECOVERED"` \| `"TIMEOUT"` \| `"ACKNOWLEDGED"` \| `"CROSSED"` \| `"THRESHOLD_CHANGED"` \| `"AWAY"` \| `"STALE"` \| `"MANUAL"` \| `null` | Why it closed; `null` while open. See [How an episode behaves](/signals/connected-ovok#how-an-episode-behaves) for each meaning. |
| `items[].episode.lastSampleAt` | `string (ISO 8601 date-time) \| null` | When the newest reading was folded in. On an open episode it shows how fresh the data is. |
| `items[].episode.durationMs` | `number \| null` | The episode length in milliseconds, as Signals reports it. |
| `items[].episode.observationCount` | `number \| null` | How many readings were folded into the episode. |
| `items[].episode.firingCount` | `number \| null` | How many of those readings were outside the band. |
| `items[].episode.minValue` | `number \| null` | The lowest reading in the episode. |
| `items[].episode.maxValue` | `number \| null` | The highest reading in the episode. |
| `items[].episode.avgValue` | `number \| null` | The average reading in the episode. |
| `items[].episode.lastValue` | `number \| null` | The newest reading folded in. On a recovered episode this is the recovery reading. |
| `items[].episode.peakValue` | `number \| null` | The peak reading of the episode. |
| `items[].episode.peakAt` | `string (ISO 8601 date-time) \| null` | When the peak reading was recorded. |
| `items[].episode.lastFiringValue` | `number \| null` | The last reading outside the band. This is the value a closed episode should headline. `null` for episodes stored before Signals tracked it; use `peakValue` then. |
| `items[].episode.lastFiringAt` | `string (ISO 8601 date-time) \| null` | When the last reading outside the band was recorded. |
| `items[].episode.lastObservationId` | `string \| null` | The id of the last evaluated reading folded in. On a recovered episode, the reading that closed it. Match it against `values[].observationId` on the detail route. |
| `items[].episode.firedBand` | `object \| null` | The band the episode was judged under: the band Signals recorded when it fired, or else the band rebuilt from its configuration history. It is not the resident's current band, so editing a threshold does not change past episodes. `null` when the band cannot be established; that never fails the read. |
| `items[].episode.firedBand.min` | `number \| null` | The lower limit, or `null` when the band has no lower limit. |
| `items[].episode.firedBand.max` | `number \| null` | The upper limit, or `null` when the band has no upper limit. |
| `items[].episode.firedBand.triggerVersion` | `number \| null` | The version of the resident's threshold rule the band belongs to. |
| `items[].carehub` | `object` | The resident context Signals does not hold. Every field except `carehub.patientId` is `null` when the resident has no device assigned or the context could not be read. |
| `items[].carehub.patientId` | `string (uuid)` | The resident's Ovok `Patient.id`. Use it for the `patient` filter and for other Slim routes. |
| `items[].carehub.patientName` | `string \| null` | The resident's label (their Resident ID): the Patient's nickname, otherwise its official given name, otherwise the first name on file. |
| `items[].carehub.locationId` | `string (uuid) \| null` | The room's Location id. |
| `items[].carehub.locationName` | `string \| null` | The room's name. |
| `items[].carehub.room` | `string \| null` | The room label, from the Location's type codings. |
| `items[].carehub.bed` | `string \| null` | The bed label, from the Location's type codings. |
| `items[].carehub.floor` | `string \| null` | The floor label, from the Location's type codings. |
| `items[].carehub.deviceId` | `string \| null` | The device serial that the Slim device routes use. |
| `items[].carehub.deviceMedplumId` | `string (uuid) \| null` | The device's FHIR `Device.id`. |
| `items[].carehub.deviceName` | `string \| null` | The device's display name. |
| `items[].carehub.organizationId` | `string (uuid) \| null` | The zone's id. A zone is the device's managing Organization. |
| `items[].carehub.organizationName` | `string \| null` | The zone's name. |
| `items[].acknowledgement` | `object \| null` | `null` until someone acknowledges the episode. |
| `items[].acknowledgement.acknowledgedAt` | `string (ISO 8601 date-time)` | When the episode was acknowledged. |
| `items[].acknowledgement.acknowledgedBy` | `string \| null` | Ovok's client id at Signals. It is the same value for every acknowledgement made through Ovok. It is not a person: do not show it as a name. |
| `items[].acknowledgement.acknowledgedActor` | `object \| null` | Who acknowledged. `null` for acknowledgements made before Ovok sent an actor, and when the session had no profile. |
| `items[].acknowledgement.acknowledgedActor.reference` | `string` | The caller's profile reference, normally `Practitioner/{id}`. Admin and service sessions can carry another profile type. |
| `items[].acknowledgement.acknowledgedActor.display` | `string \| null` | The caller's display name, captured when the episode was acknowledged. |
| `items[].noteCount` | `integer \| null` | The number of notes on this episode. `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 `Patient:read`, `Device:read` or `Location:read`, your session has no project, or you cannot access the project. |
| [`404`](/errors/not-found) | The `patient` filter names a resident who cannot be resolved or is not in your project. |
| [`422`](/errors/validation-failed) | A query parameter fails validation, for example an unknown `status`, a `since` that is not a UTC instant, a `codes` list that is malformed or longer than 32, a `limit` outside 1 to 200, or a `patient` or `cursor` that is too long. |
| [`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. This is not an empty result: retry after the delay. |
