Sleep

Get sleep statistics

Get sleep statistics using Ovok’s Slim API.

MethodPath
GET/v1/slim/sleep/statistics

Authentication · 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

Query parameters

NameTypeRequiredDescription
patientIdstring (uuid)YesResident (Patient) id.
endDatestring (ISO 8601 date-time)YesThe 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.
lastDayCountintegerNoHow many earlier days feed average. Default 7, minimum 1, maximum 30.

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

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

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.

{
  "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 }
  }
}
FieldTypeDescription
<deviceReference>objectStatistics 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>.totalSleepTimeSecondsobjectTotal sleep time, in seconds, compared with the earlier nights.
<deviceReference>.totalSleepTimeSeconds.currentnumber | nullTotal sleep time, in seconds. The night of endDate. null when the recording does not carry it.
<deviceReference>.totalSleepTimeSeconds.averagenumber | nullAverage over the earlier nights that have a recording. null when no earlier night has a value.
<deviceReference>.totalSleepTimeSeconds.diffnumber | nullcurrent minus average. null when either is null.
<deviceReference>.sleepEfficiencyPercentageobjectSleep efficiency, in percent, compared with the earlier nights.
<deviceReference>.sleepEfficiencyPercentage.currentnumber | nullSleep efficiency, in percent. The night of endDate. null when the recording does not carry it.
<deviceReference>.sleepEfficiencyPercentage.averagenumber | nullAverage over the earlier nights that have a recording. null when no earlier night has a value.
<deviceReference>.sleepEfficiencyPercentage.diffnumber | nullcurrent minus average. null when either is null.
<deviceReference>.wakeAfterSleepOnsetSecondsobjectWake after sleep onset, in seconds, compared with the earlier nights.
<deviceReference>.wakeAfterSleepOnsetSeconds.currentnumber | nullWake after sleep onset, in seconds. The night of endDate. null when the recording does not carry it.
<deviceReference>.wakeAfterSleepOnsetSeconds.averagenumber | nullAverage over the earlier nights that have a recording. null when no earlier night has a value.
<deviceReference>.wakeAfterSleepOnsetSeconds.diffnumber | nullcurrent minus average. null when either is null.
<deviceReference>.totalBedTimeSecondsobjectTotal bed time, in seconds, compared with the earlier nights.
<deviceReference>.totalBedTimeSeconds.currentnumber | nullTotal bed time, in seconds. The night of endDate. null when the recording does not carry it.
<deviceReference>.totalBedTimeSeconds.averagenumber | nullAverage over the earlier nights that have a recording. null when no earlier night has a value.
<deviceReference>.totalBedTimeSeconds.diffnumber | nullcurrent minus average. null when either is null.
<deviceReference>.sleepStartTimeobjectTime sleep started, compared with the earlier nights.
<deviceReference>.sleepStartTime.currentstring (ISO 8601 date-time) | nullTime sleep started. The night of endDate, with the project's UTC offset. null when the recording does not carry it.
<deviceReference>.sleepStartTime.averagestring (ISO 8601 date-time) | nullAverage over the earlier nights that have a recording, moved onto the day of current. null when no earlier night has a value.
<deviceReference>.sleepStartTime.diffnumber | nullcurrent minus average, in seconds. null when either is null.
<deviceReference>.sleepEndTimeobjectTime sleep ended, compared with the earlier nights.
<deviceReference>.sleepEndTime.currentstring (ISO 8601 date-time) | nullTime sleep ended. The night of endDate, with the project's UTC offset. null when the recording does not carry it.
<deviceReference>.sleepEndTime.averagestring (ISO 8601 date-time) | nullAverage over the earlier nights that have a recording, moved onto the day of current. null when no earlier night has a value.
<deviceReference>.sleepEndTime.diffnumber | nullcurrent minus average, in seconds. null when either is null.
<deviceReference>.sleepOnsetLatencySecondsobjectSleep onset latency, in seconds, compared with the earlier nights.
<deviceReference>.sleepOnsetLatencySeconds.currentnumber | nullSleep onset latency, in seconds. The night of endDate. null when the recording does not carry it.
<deviceReference>.sleepOnsetLatencySeconds.averagenumber | nullAverage over the earlier nights that have a recording. null when no earlier night has a value.
<deviceReference>.sleepOnsetLatencySeconds.diffnumber | nullcurrent minus average. null when either is null.
<deviceReference>.outOfBedCountobjectNumber of times the resident left the bed, compared with the earlier nights.
<deviceReference>.outOfBedCount.currentnumber | nullNumber of times the resident left the bed. The night of endDate. null when the recording does not carry it.
<deviceReference>.outOfBedCount.averagenumber | nullAverage over the earlier nights that have a recording, rounded to a whole number. null when no earlier night has a value.
<deviceReference>.outOfBedCount.diffnumber | nullcurrent minus average. null when either is null.
<deviceReference>.wakeUpLatencySecondsobjectWake-up latency, in seconds, compared with the earlier nights.
<deviceReference>.wakeUpLatencySeconds.currentnumber | nullWake-up latency, in seconds. The night of endDate. null when the recording does not carry it.
<deviceReference>.wakeUpLatencySeconds.averagenumber | nullAverage over the earlier nights that have a recording. null when no earlier night has a value.
<deviceReference>.wakeUpLatencySeconds.diffnumber | nullcurrent minus average. null when either is null.

Errors

StatusMeaning
400Your session has no project, or your project cannot be read.
401Bearer token is missing, invalid or expired.
403You are not a practitioner, admin or System Owner, or you lack Observation:read or Observation:search.
422A query parameter fails validation.
502The FHIR server returned an error for the sleep data query.
503The access policy cannot be read right now. Retry shortly.

Last updated on

On this page