# Get last observations

Canonical page: https://docs.ovok.com/primitives/last-observations

Returns one patient's newest FHIR `Observation` resources, up to `max` per code, newest first. Name the observation codes or categories to read.

| Method | Path |
| --- | --- |
| `GET` | `/fhir/R4/Observation/$lastn` |

The unversioned and R5 aliases are `/fhir/Observation/$lastn` and `/fhir/R5/Observation/$lastn`.

## Access requirements [#access-requirements]

Send a valid bearer token. The operation reads the Patient and its Observations as the caller, so the caller's AccessPolicy must allow both.

A Patient caller may leave out `patient` and `subject` to read its own Observations. Every other caller must name the patient with `patient` or `subject`, or the request fails with `400 INVALID_LASTN`.

Set `withAlerts=true` to include Signals alerts. This also needs the custom `signals_alerts:read` capability and Signals `read` access to the Patient. See [Signals route policies](/access-policies/signals).

## Request [#request]

Name at least one `code` or `category`. Send either `patient` or `subject`, not two different patients.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `patient` | string | Non-patient callers | The patient: `Patient/:patient-id` or `:patient-id`. |
| `subject` | string | No | Same as `patient`. |
| `code` | string | Without `category` | Observation codes, comma separated or repeated. Each is `system\|code` or `code`, for example `http://loinc.org\|8886-4`. At most 50 codes. |
| `category` | string | Without `code` | Observation categories, comma separated or repeated. |
| `max` | string | No | How many Observations to return per code, a whole number from `1` to `1000`. Defaults to `1`. |
| `withAlerts` | string | No | `true` includes the Signals alerts on the returned Observations. `false` is the default. |

Any other search parameter, such as `date`, is applied to each search as given. `_count`, `_sort`, `_offset` and `_project` are ignored.

With `code`, each code is searched on its own, so `max=2` and two codes return up to four Observations. With only `category`, Ovok reads the category's newest 1,000 Observations and keeps up to `max` per code.

```bash
curl --get 'https://api.sandbox.ovok.com/fhir/R4/Observation/$lastn' \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --data-urlencode "patient=Patient/${PATIENT_ID}" \
  --data-urlencode 'max=2' \
  --data-urlencode 'code=131328,8886-4'
```

`--get` places the supplied values in the URL query string. Set `OVOK_TOKEN` to an access token authorized for the requested patient data. This example returns up to two Observations for each of the two codes.

## Successful response [#successful-response]

The operation returns a FHIR `Bundle` with `type: searchset`. Each `entry` contains an `Observation` and its canonical `fullUrl`. Per code, Observations are ordered newest clinical time first. `total` counts the matching Observations only.

| Response path | Example | Meaning |
| --- | --- | --- |
| `resourceType` | `Bundle` | Identifies the outer FHIR resource. |
| `type` | `searchset` | Indicates the Bundle contains search results. |
| `entry[].fullUrl` | `https://api.sandbox.ovok.com/fhir/R4/Observation/<observation-id>` | Canonical URL identifying the returned Observation. |
| `entry[].resource.resourceType` | `Observation` | Each entry contains an Observation resource. |
| `entry[].resource.id` | `<observation-id>` | ID of the returned Observation. |
| `entry[].resource.status` | `final` | Clinical status of the observation. |
| `entry[].resource.subject.reference` | `Patient/<patient-id>` | Patient associated with the observation. |
| `entry[].resource.code.coding[0]` | `http://loinc.org` / `8886-4` | Code system and code identifying what was measured. |
| `entry[].resource.valueQuantity` | `72` `bpm` | Example measurement and unit. Other value types may be used. |

The returned fields depend on the stored Observation. Each entry's `resource` contains one matching Observation.

## Include alerts [#include-alerts]

With `withAlerts=true`, Ovok reads the Signals alerts on the returned Observations. It appends them after the Observations, as entries with `search.mode` set to `include`:

| Response path | Example | Meaning |
| --- | --- | --- |
| `entry[].fullUrl` | `urn:uuid:<alert-id>` | The Signals alert id. The alert is not stored in Ovok, so it has no `id`. |
| `entry[].resource.resourceType` | `DetectedIssue` | One Signals alert. |
| `entry[].resource.implicated[0].reference` | `Observation/<observation-id>` | The Observation the alert is on. |
| `entry[].search.mode` | `include` | Marks the entry as included, not a match. |

Alerts never fail the request. If they are incomplete, the Bundle carries an `OperationOutcome` entry with `search.mode` set to `outcome` and a `warning` issue:

| `issue[].code` | Meaning |
| --- | --- |
| `transient` | Signals alerts could not be read. The Observations are complete without them. |
| `too-costly` | Only some of the alerts are included. Name fewer codes or a lower `max`. |

A request with only `category` can return a `too-costly` warning too: only the category's newest 1,000 Observations were read. Name codes to reach older ones.

## Responses and errors [#responses-and-errors]

Errors are [Problem Details](/errors) (`application/problem+json`). The `type` ends in the error code, for example `/errors/invalid-lastn`.

| HTTP status | Meaning |
| --- | --- |
| `200` | Request succeeded; the body is a searchset Bundle. |
| `400` | `INVALID_LASTN`: no `code` or `category`, more than 50 codes, two different patients, no patient for a non-patient caller, `max` outside `1`-`1000`, or `withAlerts` not `true` or `false`. `SEARCH_REFUSED`: the FHIR store rejected a search, for example a bad passed-through parameter. |
| `401` | The access token is missing or invalid. |
| `403` | With `withAlerts=true`, the caller lacks `signals_alerts:read` or Signals access to the Patient. The FHIR store can also refuse a read as `SEARCH_REFUSED` with its own client status. |
| `404` | The Patient does not exist or is not visible to the caller (`SEARCH_REFUSED`). |
| `502` | The FHIR store failed. |
| `503` | The FHIR store is overloaded or unavailable. Retry later. |
| `504` | The FHIR store timed out. |
