# Get sleep statistics

Canonical page: https://docs.ovok.com/slim-apis/sleep/get-sleep-statistics

| Method | Path |
| --- | --- |
| `GET` | `/v1/slim/sleep/statistics` |

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

Returns a resident's sleep statistics for one night, grouped by device, with each metric compared against the average of the preceding nights. Use it for the sleep detail view.

**Auth:** bearer token. The caller must be a practitioner, an admin or a System Owner, and needs `Observation:read` and `Observation:search`.
**Scope:** the caller's project (from the token). Sleep data is read with your token, so Ovok AccessPolicy limits what you see.

## Request [#request]

### Query parameters [#query-parameters]

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `patientId` | `string (uuid)` | Yes | Resident (Patient) id. |
| `endDate` | `string (ISO 8601 date-time)` | Yes | The night to report, in UTC (ends in `Z`, for example `2026-09-28T00:00:00Z`). The night is the calendar day of this date in the project's time zone. |
| `lastDayCount` | `integer` | No | How many earlier days feed `average`. Default `7`, minimum `1`, maximum `30`. |

## Behaviour [#behaviour]

- The "night" is the calendar day, in the project's time zone, of `endDate`. A sleep recording belongs to the day its `effectivePeriod.end` falls on.
- `lastDayCount` is how many earlier days feed `average`. It defaults to `7` and must be between 1 and 30.
- Each device entry holds, per metric, `current` (the night of `endDate`), `average` (over the earlier nights that have a recording) and `diff`. A device with no recording for the night of `endDate` is left out.
- The response is keyed by device reference, for example `Device/3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b22`.
- When one night has several recordings, the one written last is used: the latest `meta.lastUpdated`. Its period and completeness do not count, so a shorter recording written later wins, and so can a same-day nap ending after the night. A metric it does not carry is `null`, never taken from another recording. The PDF export's sleep table uses the same rule, and so do the `GET /v1/slim/trends/graphs` charts where they can match a night's readings to its recordings.
- `average` and `diff` use each earlier night's latest-written recording the same way.
- Only recordings that end inside one of the resident's use periods of their device are counted, before a night's recording is picked. So a previous resident's night that ended before the device was handed over, but reached Ovok after it and was stored under this resident, is not shown. A resident with no device use history has all recordings counted. The PDF export and the `GET /v1/slim/trends/graphs` charts apply the same filter.
- Once a resident has any use period, recordings of a device with no period of theirs, and those from before a device's earliest period, are not counted. A device assigned before use periods were recorded gets its first one on its next edit in Ovok, starting at the Device's last write before that edit. Each device whose recordings in a request all drop is counted in the `sleep.device_use_device_dropped` metric and logged at most once a minute.
- Ovok reads the `sleep-stats` observations first and falls back to the LOINC pair `93832-4` (sleep duration) and `103216-8` (out-of-bed count) when there are none.
- The response is `{}` when no qualifying recording exists.
- Results are cached for up to 60 seconds per project, resident, `endDate` and `lastDayCount`. A write to the resident's data invalidates the cache sooner.

## Example [#example]

```bash
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/sleep/statistics?patientId=3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21&endDate=2026-09-28T00:00:00Z&lastDayCount=7' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"
```

## Successful response [#successful-response]

`200` — Successfully retrieved sleep statistics data grouped by device

The response is an object keyed by device reference. Time values carry the project's UTC offset, `+02:00` in this example.

```json
{
  "Device/3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b22": {
    "totalSleepTimeSeconds": { "current": 27600, "average": 26900, "diff": 700 },
    "sleepEfficiencyPercentage": { "current": 90, "average": 89.5, "diff": 0.5 },
    "wakeAfterSleepOnsetSeconds": { "current": 1800, "average": 2100, "diff": -300 },
    "totalBedTimeSeconds": { "current": 30600, "average": 30000, "diff": 600 },
    "sleepStartTime": {
      "current": "2026-09-27T22:14:00.000+02:00",
      "average": "2026-09-27T22:30:00.000+02:00",
      "diff": -960
    },
    "sleepEndTime": {
      "current": "2026-09-28T06:24:00.000+02:00",
      "average": "2026-09-28T06:30:00.000+02:00",
      "diff": -360
    },
    "sleepOnsetLatencySeconds": { "current": 900, "average": 1200, "diff": -300 },
    "outOfBedCount": { "current": 1, "average": 2, "diff": -1 },
    "wakeUpLatencySeconds": { "current": 300, "average": 420, "diff": -120 }
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `<deviceReference>` | `object` | Statistics of one device. The key is the device reference, for example `Device/3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b22`. A device with no recording for the night of `endDate` has no key. |
| `<deviceReference>.totalSleepTimeSeconds` | `object` | Total sleep time, in seconds, compared with the earlier nights. |
| `<deviceReference>.totalSleepTimeSeconds.current` | `number \| null` | Total sleep time, in seconds. The night of `endDate`. `null` when the recording does not carry it. |
| `<deviceReference>.totalSleepTimeSeconds.average` | `number \| null` | Average over the earlier nights that have a recording. `null` when no earlier night has a value. |
| `<deviceReference>.totalSleepTimeSeconds.diff` | `number \| null` | `current` minus `average`. `null` when either is `null`. |
| `<deviceReference>.sleepEfficiencyPercentage` | `object` | Sleep efficiency, in percent, compared with the earlier nights. |
| `<deviceReference>.sleepEfficiencyPercentage.current` | `number \| null` | Sleep efficiency, in percent. The night of `endDate`. `null` when the recording does not carry it. |
| `<deviceReference>.sleepEfficiencyPercentage.average` | `number \| null` | Average over the earlier nights that have a recording. `null` when no earlier night has a value. |
| `<deviceReference>.sleepEfficiencyPercentage.diff` | `number \| null` | `current` minus `average`. `null` when either is `null`. |
| `<deviceReference>.wakeAfterSleepOnsetSeconds` | `object` | Wake after sleep onset, in seconds, compared with the earlier nights. |
| `<deviceReference>.wakeAfterSleepOnsetSeconds.current` | `number \| null` | Wake after sleep onset, in seconds. The night of `endDate`. `null` when the recording does not carry it. |
| `<deviceReference>.wakeAfterSleepOnsetSeconds.average` | `number \| null` | Average over the earlier nights that have a recording. `null` when no earlier night has a value. |
| `<deviceReference>.wakeAfterSleepOnsetSeconds.diff` | `number \| null` | `current` minus `average`. `null` when either is `null`. |
| `<deviceReference>.totalBedTimeSeconds` | `object` | Total bed time, in seconds, compared with the earlier nights. |
| `<deviceReference>.totalBedTimeSeconds.current` | `number \| null` | Total bed time, in seconds. The night of `endDate`. `null` when the recording does not carry it. |
| `<deviceReference>.totalBedTimeSeconds.average` | `number \| null` | Average over the earlier nights that have a recording. `null` when no earlier night has a value. |
| `<deviceReference>.totalBedTimeSeconds.diff` | `number \| null` | `current` minus `average`. `null` when either is `null`. |
| `<deviceReference>.sleepStartTime` | `object` | Time sleep started, compared with the earlier nights. |
| `<deviceReference>.sleepStartTime.current` | `string (ISO 8601 date-time) \| null` | Time sleep started. The night of `endDate`, with the project's UTC offset. `null` when the recording does not carry it. |
| `<deviceReference>.sleepStartTime.average` | `string (ISO 8601 date-time) \| null` | Average over the earlier nights that have a recording, moved onto the day of `current`. `null` when no earlier night has a value. |
| `<deviceReference>.sleepStartTime.diff` | `number \| null` | `current` minus `average`, in seconds. `null` when either is `null`. |
| `<deviceReference>.sleepEndTime` | `object` | Time sleep ended, compared with the earlier nights. |
| `<deviceReference>.sleepEndTime.current` | `string (ISO 8601 date-time) \| null` | Time sleep ended. The night of `endDate`, with the project's UTC offset. `null` when the recording does not carry it. |
| `<deviceReference>.sleepEndTime.average` | `string (ISO 8601 date-time) \| null` | Average over the earlier nights that have a recording, moved onto the day of `current`. `null` when no earlier night has a value. |
| `<deviceReference>.sleepEndTime.diff` | `number \| null` | `current` minus `average`, in seconds. `null` when either is `null`. |
| `<deviceReference>.sleepOnsetLatencySeconds` | `object` | Sleep onset latency, in seconds, compared with the earlier nights. |
| `<deviceReference>.sleepOnsetLatencySeconds.current` | `number \| null` | Sleep onset latency, in seconds. The night of `endDate`. `null` when the recording does not carry it. |
| `<deviceReference>.sleepOnsetLatencySeconds.average` | `number \| null` | Average over the earlier nights that have a recording. `null` when no earlier night has a value. |
| `<deviceReference>.sleepOnsetLatencySeconds.diff` | `number \| null` | `current` minus `average`. `null` when either is `null`. |
| `<deviceReference>.outOfBedCount` | `object` | Number of times the resident left the bed, compared with the earlier nights. |
| `<deviceReference>.outOfBedCount.current` | `number \| null` | Number of times the resident left the bed. The night of `endDate`. `null` when the recording does not carry it. |
| `<deviceReference>.outOfBedCount.average` | `number \| null` | Average over the earlier nights that have a recording, rounded to a whole number. `null` when no earlier night has a value. |
| `<deviceReference>.outOfBedCount.diff` | `number \| null` | `current` minus `average`. `null` when either is `null`. |
| `<deviceReference>.wakeUpLatencySeconds` | `object` | Wake-up latency, in seconds, compared with the earlier nights. |
| `<deviceReference>.wakeUpLatencySeconds.current` | `number \| null` | Wake-up latency, in seconds. The night of `endDate`. `null` when the recording does not carry it. |
| `<deviceReference>.wakeUpLatencySeconds.average` | `number \| null` | Average over the earlier nights that have a recording. `null` when no earlier night has a value. |
| `<deviceReference>.wakeUpLatencySeconds.diff` | `number \| null` | `current` minus `average`. `null` when either is `null`. |

## Errors [#errors]

| Status | Meaning |
| --- | --- |
| [`400`](/errors/malformed-request) | Your session has no project, or your project cannot be read. |
| [`401`](/errors/unauthenticated) | Bearer token is missing, invalid or expired. |
| [`403`](/errors/forbidden) | You are not a practitioner, admin or System Owner, or you lack `Observation:read` or `Observation:search`. |
| [`422`](/errors/validation-failed) | A query parameter fails validation. |
| [`502`](/errors/upstream-error) | The FHIR server returned an error for the sleep data query. |
| [`503`](/errors/service-unavailable) | The access policy cannot be read right now. Retry shortly. |
