Skip to main content

Get sleep statistics

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 Medplum's access policy limits what you see.

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.
  • 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

Errors​

StatusMeaning
400Your session has no project.
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.
502Medplum returned an error for the sleep data query.