Get trends graphs
Get trends graphs using Ovok’s Slim API.
| Method | Path |
|---|---|
GET | /v1/slim/trends/graphs |
Authentication · Access policies
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 single day within the last 14, use GET /v1/slim/trends/realtime.
Auth: bearer token. The caller must be a practitioner, an admin or a System Owner, and 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 Ovok AccessPolicy limits what you see.
Request
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
patientId | string (uuid) | Yes | Resident (Patient) id. |
startDate | string (ISO 8601 date-time) | Yes | Start of the range, in UTC (ends in Z, for example 2026-09-25T00:00:00Z). Must not be after endDate. |
endDate | string (ISO 8601 date-time) | Yes | End of the range, in UTC (ends in Z). |
graphType | string (comma-separated) | Yes | Graph types to return: heartRate, respiratoryRate or both, for example heartRate,respiratoryRate. Repeated entries are ignored. |
Behaviour
graphTypeis a comma-separated list ofheartRateandrespiratoryRate. Repeated entries are ignored.startDatemust not be afterendDate.- 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, 2,881 points in all.endDateonly 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/statisticsdoes. 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_droppedmetric and logged at most once a minute. - The use periods are read on every uncached call. If the FHIR server returns an error for that read, the route answers
502rather than chart a night it cannot check. If the request fails before a response is received, the route returns the FHIR server's status or500. - 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 ruleGET /v1/slim/sleep/statisticsuses. 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 a batch block can end 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.pointTimestampandpointTimestampRangeshow which readings filled it. When several readings fall in one bucket, the last one wins. maxThreshold,minThreshold,maxBaseLineandminBaseLineare the values that applied at that time. Each point carries the limit in force at its own time, so the lines step when a limit changes in the range. A new 7-day baseline does not step the line. If the threshold change history cannot be read, each point carries the current limits. A bucket without a reading still carries its limits, so the lines stay continuous. Limits are resolved from the resident's project even when the caller belongs to a parent organization.- 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, bothheartRateandrespiratoryRateare{}. - A failed read of the readings or the statistics does not fail the request: that part of the chart comes back empty. Only the read of the use periods fails it, with
502. - A failed read of the resident returns its error status instead of an empty chart. A resident read that returns
404or410gives an empty chart with200. - Results are cached for up to 60 seconds. A write to the resident's data invalidates the cache sooner.
Example
curl -X GET 'https://api.sandbox.ovok.com/v1/slim/trends/graphs?patientId=3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21&startDate=2026-09-25T00:00:00Z&endDate=2026-09-28T00:00:00Z&graphType=heartRate,respiratoryRate' \
-H "Authorization: Bearer ${OVOK_TOKEN}"Successful response
200 — Successfully retrieved trends data grouped by device and graph type
The response is an object keyed by graph type, then by device key. The example is the over-day chart for the request above: three daily points at 09:00 local time (07:00 UTC), the middle one without a reading.
{
"heartRate": {
"Demo-3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b22": {
"dataPoints": [
{
"timestamp": "2026-09-26T07:00:00.000Z",
"timestampMs": 1790406000000,
"data": 71.4,
"maxThreshold": 100,
"minThreshold": 50,
"maxBaseLine": 84,
"minBaseLine": 60,
"pointTimestamp": "2026-09-26T05:58:00.000Z",
"pointTimestampRange": { "start": "2026-09-26T05:58:00.000Z", "end": "2026-09-26T05:58:00.000Z" }
},
{
"timestamp": "2026-09-27T07:00:00.000Z",
"timestampMs": 1790492400000,
"data": null,
"maxThreshold": 100,
"minThreshold": 50,
"maxBaseLine": 84,
"minBaseLine": 60
},
{
"timestamp": "2026-09-28T07:00:00.000Z",
"timestampMs": 1790578800000,
"data": 68.2,
"maxThreshold": 100,
"minThreshold": 50,
"maxBaseLine": 84,
"minBaseLine": 60,
"pointTimestamp": "2026-09-28T06:12:00.000Z",
"pointTimestampRange": { "start": "2026-09-28T06:12:00.000Z", "end": "2026-09-28T06:12:00.000Z" }
}
],
"stats": {
"average": 69.8,
"max": 71.4,
"min": 68.2,
"total": 2
}
}
},
"respiratoryRate": {
"Demo-3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b22": {
"dataPoints": [
{
"timestamp": "2026-09-26T07:00:00.000Z",
"timestampMs": 1790406000000,
"data": 14.2,
"maxThreshold": 24,
"minThreshold": 8,
"maxBaseLine": 18,
"minBaseLine": 12,
"pointTimestamp": "2026-09-26T05:58:00.000Z",
"pointTimestampRange": { "start": "2026-09-26T05:58:00.000Z", "end": "2026-09-26T05:58:00.000Z" }
},
{
"timestamp": "2026-09-27T07:00:00.000Z",
"timestampMs": 1790492400000,
"data": null,
"maxThreshold": 24,
"minThreshold": 8,
"maxBaseLine": 18,
"minBaseLine": 12
},
{
"timestamp": "2026-09-28T07:00:00.000Z",
"timestampMs": 1790578800000,
"data": 13.8,
"maxThreshold": 24,
"minThreshold": 8,
"maxBaseLine": 18,
"minBaseLine": 12,
"pointTimestamp": "2026-09-28T06:12:00.000Z",
"pointTimestampRange": { "start": "2026-09-28T06:12:00.000Z", "end": "2026-09-28T06:12:00.000Z" }
}
],
"stats": {
"average": 14,
"max": 14.2,
"min": 13.8,
"total": 2
}
}
}
}| Field | Type | Description |
|---|---|---|
<graphType> | object | One key per requested graph type, plus heartRate and respiratoryRate when nothing can be charted. Each value maps device keys to series. A type with no data is {}. |
<graphType>.<deviceKey> | object | Series of one device. The key is <manufacturer>-<device id>, for example Demo-3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b22. A resident who changed device has one entry per device. |
<graphType>.<deviceKey>.dataPoints | object[] | Every bucket of the chart, oldest first, including buckets without a reading. |
<graphType>.<deviceKey>.dataPoints[].timestamp | string (ISO 8601 date-time) | Bucket time in UTC. The bucket covers the interval that ends at this time. |
<graphType>.<deviceKey>.dataPoints[].timestampMs | integer | Same time in Unix milliseconds. |
<graphType>.<deviceKey>.dataPoints[].data | number | null | Value of the bucket, in the unit of the graph type. null when no reading fell in the bucket. |
<graphType>.<deviceKey>.dataPoints[].maxThreshold | number | Upper alert limit that applied at this time. Omitted when none applies. |
<graphType>.<deviceKey>.dataPoints[].minThreshold | number | Lower alert limit that applied at this time. Omitted when none applies. |
<graphType>.<deviceKey>.dataPoints[].maxBaseLine | number | Upper baseline value that applied at this time. Omitted when none applies. |
<graphType>.<deviceKey>.dataPoints[].minBaseLine | number | Lower baseline value that applied at this time. Omitted when none applies. |
<graphType>.<deviceKey>.dataPoints[].pointTimestamp | string (ISO 8601 date-time) | Time of the reading that filled the bucket. Omitted when data is null. |
<graphType>.<deviceKey>.dataPoints[].pointTimestampRange | object | First and last reading that contributed to the bucket. Omitted when data is null. |
<graphType>.<deviceKey>.dataPoints[].pointTimestampRange.start | string (ISO 8601 date-time) | Time of the first reading that contributed. |
<graphType>.<deviceKey>.dataPoints[].pointTimestampRange.end | string (ISO 8601 date-time) | Time of the last reading that contributed. |
<graphType>.<deviceKey>.stats | object | Summary of the buckets that have data. |
<graphType>.<deviceKey>.stats.average | number | null | Mean of the buckets that have data, to 2 decimals. null when no bucket has data or the mean is 0. |
<graphType>.<deviceKey>.stats.max | number | null | Highest value. null when no bucket has data or the value is 0 or less. |
<graphType>.<deviceKey>.stats.min | number | null | Lowest value. null when no bucket has data or the value is 0 or less. |
<graphType>.<deviceKey>.stats.total | integer | Number of buckets that have data. |
Errors
| Status | Meaning |
|---|---|
400 | Your session has no project, or your project cannot be read. |
401 | Bearer token is missing, invalid or expired. |
403 | You are not a practitioner, admin or System Owner, you lack Organization:read, Device:read, Patient:read or DocumentReference:read, or the FHIR server refused the resident read. |
422 | A query parameter fails validation, or startDate is after endDate. |
500 | The request to the FHIR server failed before a response arrived. |
502 | The FHIR server returned an error while reading the resident's device use periods. |
503 | The access policy cannot be read right now. Retry shortly. |
Last updated on