SlimSlim/Trends

Get trends graphs from Signals

  • Sandbox: available
  • On your own host? Choose https://{host} in the playground.
GET
/v2/slim/trends/graphs

Returns a resident's vitals and sleep episodes over a date range, grouped by graph type and device, with threshold and baseline values and summary statistics. Use it to draw the trend charts: within a day it returns every reading Signals holds, over several days the daily means.

Auth: The caller needs Organization:read, Device:read, Patient:read and DocumentReference:read. Scope: the caller's project (from the token). The resident is read with your token, so Medplum's access policy limits who you can chart.

Behaviour

  • graphType is a comma-separated list of heartRate, respiratoryRate, oxygenSaturation, pulseRate, perfusionIndex, bodyTemperature, systolicBloodPressure, diastolicBloodPressure, heartRateVariability and sleepEpisodes. Repeated entries are ignored. startDate must not be after endDate. With sleepEpisodes in the list the range must be an in-day chart, one local calendar day (24 hours, 23 or 25 on a clock change) or an exact window, else the route answers 422 and charts nothing; the vitals alone take any range.
  • Days run from midnight to midnight in the project's time zone (default Europe/Berlin), the days Signals computes its daily means over.
  • A range of one day or less is an in-day chart: every reading of the local calendar day of startDate, from midnight to midnight, each at the time it was taken. endDate only decides which kind of chart you get, unless window=exact asks for the window itself. Readings sent on their own and inside a combined device reading both count; a combined reading at a time the vital already has a reading is charted once. Readings without a value are left out. A sensor sending once a second gives up to 86,400 readings per vital per day; a day Signals cannot return in one read (more than 500,000 readings, or more than 12 seconds) answers 503 like a Signals outage.
  • A range of two or more days is an over-day chart: one point per local calendar day from startDate, stamped at the day's last instant. Each point is the day's mean, from midnight to midnight, as the home's derived-reading triggers record it in Signals. A day with no mean shows the night Medplum's statistics hold ending on that day, with batch readings filling nights that have none.
  • Heart and respiratory rate fall back to Medplum where Signals cannot chart them: an in-day chart Signals holds no reading of, or an over-day chart with a day Signals has no mean for. The other vitals come from Signals only.
  • Signals readings are kept to the resident's use periods of the device that sent them: a reading counts when its device was in use by the resident at the reading's time. A resident with no device use history keeps every reading; once they have one, a reading that names no device is dropped.
  • Readings older than Signals keeps in its database are read from its archive, in the same way.
  • sleepEpisodes has one point per episode that overlaps the range, oldest first. timestamp is the episode's start and pointTimestampRange its start and end; data is the seconds asleep inside it. The episode still running has no end and data: null. Episodes are recorded by the home's live sleep trigger as the combined device readings arrive, and are not bucketed: an episode starts at the first reading that finds the resident in bed and asleep, and ends at the first reading that finds them awake or out of bed, or 30 minutes after the device last sent while they slept. stats are over the seconds asleep.
  • The Medplum fallback keeps the rules it always had. Before a night's recording is picked, it drops the readings and sleep statistics that end outside the resident's use periods of their device, as GET /v1/slim/sleep/statistics does. When a night has several sleep recordings left, it shows only the readings of the one whose sleep statistics were written last (latest meta.lastUpdated), matching statistics by the recording's exact period and batch blocks by their start.
  • The use periods are read on every uncached call. When Medplum answers that read with an error, the route answers 502 rather than chart a night it cannot check.
  • If Signals cannot be read, the route answers 503 with error: "signals_unavailable" and retryAfterSec, never a partial or empty chart. It answers the same, before reading anything, when the server is already running its limit of Signals reads.
  • An over-day chart returns every day, and a day without a reading has data: null; pointTimestamp and pointTimestampRange show which reading filled it. An in-day chart returns readings only, so it has no empty points.
  • maxThreshold, minThreshold, maxBaseLine and minBaseLine are the values that applied at that time. They are left out when none apply, and when the threshold lookup fails the chart still returns without them. Only heartRate and respiratoryRate carry them.
  • Devices are keyed <manufacturer>-<device id>. Signals series are keyed by the resident's current device, else the device they wore last, else Patient/<id>; a Medplum fallback series is keyed by the device that sent it.
  • A graph type with no data in the range comes back as {}. When nothing at all can be charted, both heartRate and respiratoryRate are {}.
  • window=exact charts exactly startDate to endDate, whatever local days it falls across, so the last few hours still read right after midnight. It returns every reading in the window at the time it was taken, and the sleep episodes that overlap it, with the same threshold and baseline values as a day chart. The window may cover at most 24 hours, else the route answers 422. Without it, or with window=day, the chart is the local calendar day of startDate as before.
  • Results are cached for up to 15 seconds while the range may still be running, and up to 60 seconds once it has ended. A day chart and an exact window of the same dates are cached apart. A batch or statistics write to the resident's data invalidates the cache sooner.

Example

curl -X GET 'https://api.sandbox.ovok.com/v2/slim/trends/graphs?patientId=c3499c27-2973-0a7f-807e-fb8676a92dcb&startDate=2026-09-02T00:00:00Z&endDate=2026-09-02T00:00:00Z&graphType=heartRate,respiratoryRate,sleepEpisodes' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'

The last six hours, wherever local midnight falls in them:

curl -X GET 'https://api.sandbox.ovok.com/v2/slim/trends/graphs?patientId=c3499c27-2973-0a7f-807e-fb8676a92dcb&startDate=2026-09-02T19:00:00Z&endDate=2026-09-03T01:00:00Z&graphType=heartRate,respiratoryRate,sleepEpisodes&window=exact' \  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'
{  "heartRate": {    "Sleepiz-5f0c...": {      "dataPoints": [        {          "timestamp": "2026-09-02T03:12:30.000Z",          "timestampMs": 1788318750000,          "data": 58,          "maxThreshold": 100,          "minThreshold": 60,          "pointTimestamp": "2026-09-02T03:12:30.000Z"        }      ],      "stats": { "average": 58, "max": 58, "min": 58, "total": 1 }    }  },  "respiratoryRate": {},  "sleepEpisodes": {    "Sleepiz-5f0c...": {      "dataPoints": [        {          "timestamp": "2026-09-01T20:10:00.000Z",          "timestampMs": 1788293400000,          "data": 27000,          "pointTimestampRange": { "start": "2026-09-01T20:10:00.000Z", "end": "2026-09-02T04:40:00.000Z" }        }      ],      "stats": { "average": 27000, "max": 27000, "min": 27000, "total": 1 }    }  }}

Who can call it: a practitioner, a project admin or a System Owner session. See roles.

Authorization

bearer
headerAuthorizationBearer <JWT>

Query Parameters

patientId*string
Formatuuid
startDate*string
Formatdate-time
endDate*string
Formatdate-time
graphType*string
window?string
Value in"day""exact"

Response Body

Successfully retrieved trends data grouped by device and graph type

application/json
  1. response

Trends data grouped by graph type and device ID

[key: string]?
Example Request
curl -X GET 'https://api.sandbox.ovok.com/v2/slim/trends/graphs?patientId=497f6eca-6276-4993-bfeb-53cbbbba6f08&startDate=2019-08-24T14%3A15%3A22Z&endDate=2019-08-24T14%3A15%3A22Z&graphType=string'
Example Response
{  "property1": {    "property1": {      "dataPoints": [        {          "timestamp": "string",          "timestampMs": 0,          "data": 0,          "maxThreshold": 0,          "minThreshold": 0,          "maxBaseLine": 0,          "minBaseLine": 0,          "pointTimestamp": "string",          "pointTimestampRange": {            "start": "string",            "end": "string"          }        }      ],      "stats": {        "average": 0,        "max": 0,        "min": 0,        "total": 0      }    },    "property2": {      "dataPoints": [        {          "timestamp": "string",          "timestampMs": 0,          "data": 0,          "maxThreshold": 0,          "minThreshold": 0,          "maxBaseLine": 0,          "minBaseLine": 0,          "pointTimestamp": "string",          "pointTimestampRange": {            "start": "string",            "end": "string"          }        }      ],      "stats": {        "average": 0,        "max": 0,        "min": 0,        "total": 0      }    }  },  "property2": {    "property1": {      "dataPoints": [        {          "timestamp": "string",          "timestampMs": 0,          "data": 0,          "maxThreshold": 0,          "minThreshold": 0,          "maxBaseLine": 0,          "minBaseLine": 0,          "pointTimestamp": "string",          "pointTimestampRange": {            "start": "string",            "end": "string"          }        }      ],      "stats": {        "average": 0,        "max": 0,        "min": 0,        "total": 0      }    },    "property2": {      "dataPoints": [        {          "timestamp": "string",          "timestampMs": 0,          "data": 0,          "maxThreshold": 0,          "minThreshold": 0,          "maxBaseLine": 0,          "minBaseLine": 0,          "pointTimestamp": "string",          "pointTimestampRange": {            "start": "string",            "end": "string"          }        }      ],      "stats": {        "average": 0,        "max": 0,        "min": 0,        "total": 0      }    }  }}

Get trends graphs GET

Returns a resident's heart rate and respiratory rate over a date range, grouped by graph type and device, with threshold and baseline values and summary statistics. Use it to draw the trend charts. For every reading of a day and the sleep episodes, from Signals, use `GET /v2/slim/trends/graphs`. **Auth:** The caller needs `Organization:read`, `Device:read`, `Patient:read` and `DocumentReference:read`. **Scope:** the caller's project (from the token). Observations are read with your token, so Medplum's access policy limits what you see. ## Behaviour - `graphType` is a comma-separated list of `heartRate` and `respiratoryRate`. Repeated entries are ignored. `startDate` must not be after `endDate`. - Days are cut at the project's time zone (default `Europe/Berlin`). The chart for a day starts at 09:00 local time, so a night stays in one day. - A range of two or more days is an over-day chart: one point per day, at 09:00 local time, starting the day after `startDate`. Each point is the day's mean from the pre-computed statistics, with batch readings filling nights that have none. - A range of one day or less is an in-day chart: 30-second points across the 24 hours that start at 09:00 local time on `startDate`. `endDate` only decides which kind of chart you get. In-day points come from batch readings only. - Before a night's recording is picked, both charts drop the readings and sleep statistics that end outside the resident's use periods of their device, as `GET /v1/slim/sleep/statistics` does. 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 charted. A resident with no device use history keeps all of them. - Once a resident has any use period, this also drops the readings of a device with no period of theirs, and those from before a device's earliest period. 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, so its readings from before then are not charted. Each device whose readings in a request all drop is counted in the `sleep.device_use_device_dropped` metric and logged at most once a minute. - The use periods are read on every uncached call. When Medplum answers that read with an error, the route answers `502` rather than chart a night it cannot check; when the request itself fails, the route fails with Medplum's status, or `500`. - When a night (the calendar day its recordings end on, in the project's time zone) has several sleep recordings left, both charts show only the readings of the one whose sleep statistics were written last (latest `meta.lastUpdated`): its heart and respiratory rate statistics, matched by the recording's exact period, and its batch readings, matched by their start (below). That is the rule `GET /v1/slim/sleep/statistics` uses. A night with no sleep statistics goes by its heart and respiratory rate statistics' write times. A night with one recording left, a night with batch readings only, and a night none of whose readings belongs to the chosen recording are charted with all the readings left. Readings with no end time cannot be put on a night, so neither rule applies to them: they are always charted. - Sleep statistics are read over the chart's range, which ends at 09:00 local time on its last day, so a recording that starts later that day is not weighed. - A batch block is matched by its start, because Sleepiz ends one up to about ten minutes before its recording: it belongs to the recording that starts at the same instant and ends at or after it, at most 15 minutes later, the earliest such end when two recordings share the start. A batch block that starts at any other time belongs to no recording, so on a night with several recordings it is dropped: a chosen recording whose only heart rate reading is a batch block that starts after the recording shows no heart rate for that night, while its respiratory rate still shows. - Every bucket is returned. A bucket without a reading has `data: null`. `pointTimestamp` and `pointTimestampRange` show which readings filled it. - `maxThreshold`, `minThreshold`, `maxBaseLine` and `minBaseLine` are the values that applied at that time. They are left out when none apply, and when the threshold lookup fails the chart still returns without them. - When a heart or breathing rate limit changed inside the range (a nurse's edit or a home-wide save), each point carries the limit in force at its own time, as Signals recorded it, so the lines step where the limit changed. Points after the last change carry the limits the limits screen shows. If Signals' change history cannot be read, every point carries the current limits. - Devices are keyed `<manufacturer>-<device id>`. A resident who changed device has one entry per device. - A graph type with no data in the range comes back as `{}`. When nothing at all can be charted, both `heartRate` and `respiratoryRate` are `{}`. - Results are cached for up to 60 seconds. A write to the resident's data invalidates the cache sooner. ## Example ```bash curl -X GET 'https://api.sandbox.ovok.com/v1/slim/trends/graphs?patientId=c3499c27-2973-0a7f-807e-fb8676a92dcb&startDate=2026-09-01T00:00:00Z&endDate=2026-09-30T00:00:00Z&graphType=heartRate,respiratoryRate' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ``` ```json { "heartRate": { "Sleepiz-5f0c...": { "dataPoints": [ { "timestamp": "2026-09-02T07:00:00.000Z", "timestampMs": 1788332400000, "data": 72, "maxThreshold": 100, "minThreshold": 60, "pointTimestamp": "2026-09-02T05:41:00.000Z" } ], "stats": { "average": 72, "max": 72, "min": 72, "total": 1 } } }, "respiratoryRate": {} } ``` **Who can call it:** a practitioner, a project admin or a System Owner session. See [roles](/access-policies#who-can-call-a-route).

Get terms and conditions consent GET

Returns whether the signed-in practitioner has accepted the current terms and conditions. Use it to decide whether to show the terms prompt. **Auth:** The profile must be a `Practitioner`. The caller's access policy must grant `Consent:read` and `Consent:search` (a project admin who holds no access policy skips this check). **Scope:** The caller's practitioner profile in the caller's project (from the token). ## Behaviour - `termsAndConditionsConsent` is `true` only when an acceptance is on file and either matches the currently published terms version or no version has been published yet. - Publishing new terms turns it `false` for everyone until they accept again. - The published version is the one of the root project of your project tree: a child project follows its parent's terms. Without one, the platform-wide version applies. - `GET /v1/me/consent/legal` returns the same acceptance with its dates and terms link. ## Example ```bash curl -X GET 'https://api.sandbox.ovok.com/v1/slim/user/terms-and-conditions-consent' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' ``` **Who can call it:** a practitioner, a project admin or a System Owner session. See [roles](/access-policies#who-can-call-a-route).