Trends

Get trends graphs

Get trends graphs using Ovok’s Slim API.

MethodPath
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

NameTypeRequiredDescription
patientIdstring (uuid)YesResident (Patient) id.
startDatestring (ISO 8601 date-time)YesStart of the range, in UTC (ends in Z, for example 2026-09-25T00:00:00Z). Must not be after endDate.
endDatestring (ISO 8601 date-time)YesEnd of the range, in UTC (ends in Z).
graphTypestring (comma-separated)YesGraph types to return: heartRate, respiratoryRate or both, for example heartRate,respiratoryRate. Repeated entries are ignored.

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, 2,881 points in all. 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. If the FHIR server returns an error for that read, the route answers 502 rather than chart a night it cannot check. If the request fails before a response is received, the route returns the FHIR server'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 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. pointTimestamp and pointTimestampRange show which readings filled it. When several readings fall in one bucket, the last one wins.
  • maxThreshold, minThreshold, maxBaseLine and minBaseLine are 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, both heartRate and respiratoryRate are {}.
  • 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 404 or 410 gives an empty chart with 200.
  • 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
      }
    }
  }
}
FieldTypeDescription
<graphType>objectOne 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>objectSeries 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>.dataPointsobject[]Every bucket of the chart, oldest first, including buckets without a reading.
<graphType>.<deviceKey>.dataPoints[].timestampstring (ISO 8601 date-time)Bucket time in UTC. The bucket covers the interval that ends at this time.
<graphType>.<deviceKey>.dataPoints[].timestampMsintegerSame time in Unix milliseconds.
<graphType>.<deviceKey>.dataPoints[].datanumber | nullValue of the bucket, in the unit of the graph type. null when no reading fell in the bucket.
<graphType>.<deviceKey>.dataPoints[].maxThresholdnumberUpper alert limit that applied at this time. Omitted when none applies.
<graphType>.<deviceKey>.dataPoints[].minThresholdnumberLower alert limit that applied at this time. Omitted when none applies.
<graphType>.<deviceKey>.dataPoints[].maxBaseLinenumberUpper baseline value that applied at this time. Omitted when none applies.
<graphType>.<deviceKey>.dataPoints[].minBaseLinenumberLower baseline value that applied at this time. Omitted when none applies.
<graphType>.<deviceKey>.dataPoints[].pointTimestampstring (ISO 8601 date-time)Time of the reading that filled the bucket. Omitted when data is null.
<graphType>.<deviceKey>.dataPoints[].pointTimestampRangeobjectFirst and last reading that contributed to the bucket. Omitted when data is null.
<graphType>.<deviceKey>.dataPoints[].pointTimestampRange.startstring (ISO 8601 date-time)Time of the first reading that contributed.
<graphType>.<deviceKey>.dataPoints[].pointTimestampRange.endstring (ISO 8601 date-time)Time of the last reading that contributed.
<graphType>.<deviceKey>.statsobjectSummary of the buckets that have data.
<graphType>.<deviceKey>.stats.averagenumber | nullMean of the buckets that have data, to 2 decimals. null when no bucket has data or the mean is 0.
<graphType>.<deviceKey>.stats.maxnumber | nullHighest value. null when no bucket has data or the value is 0 or less.
<graphType>.<deviceKey>.stats.minnumber | nullLowest value. null when no bucket has data or the value is 0 or less.
<graphType>.<deviceKey>.stats.totalintegerNumber of buckets that have data.

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, you lack Organization:read, Device:read, Patient:read or DocumentReference:read, or the FHIR server refused the resident read.
422A query parameter fails validation, or startDate is after endDate.
500The request to the FHIR server failed before a response arrived.
502The FHIR server returned an error while reading the resident's device use periods.
503The access policy cannot be read right now. Retry shortly.

Last updated on

On this page