Get realtime trends graphs
Get realtime trends graphs using Ovok’s Slim API.
| Method | Path |
|---|---|
GET | /v1/slim/trends/realtime |
Authentication · Access policies
Returns the resident's readings from Signals, one data point per reading, in the same shape as GET /v1/slim/trends/graphs. Use it for the live part of a chart, or to look at any day of the last 14.
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 resident must be in the caller's project or one of its sub-projects (not its parent). A resident outside that scope answers 404, the same as one that does not exist.
Request
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
patientId | string (uuid) | Yes | Resident (Patient) id. |
startTime | string (ISO 8601 date-time) | Yes | Start of the window, in UTC (ends in Z, for example 2026-09-28T07:40:00Z). Must not be after endTime, and must not be more than 14 days ago. |
endTime | string (ISO 8601 date-time) | Yes | End of the window, in UTC (ends in Z). At most 24 hours after startTime. |
graphType | string (comma-separated) | Yes | Graph types to return. One or more of heartRate, respiratoryRate, oxygenSaturation, pulseRate, perfusionIndex, bodyTemperature, systolicBloodPressure, diastolicBloodPressure and heartRateVariability, for example heartRate,respiratoryRate. Repeated entries are ignored. |
Behaviour
- The chart covers exactly
[startTime, endTime]. Unlike/graphs, it does not snap to monitoring days. - Every reading in the window comes back as Signals recorded it, oldest first: one data point per reading, at the reading's own time, with its own value. Nothing is bucketed or averaged, and no empty points are added between readings, so a silent device shows as a stretch with no points. A reading with no numeric value comes back with
data: null. - The response grows with the device's cadence: a day of readings every 30 seconds is about 2,900 points per graph type.
- A resident's readings are charted whatever device they wear now. They use one key: the most recently assigned device, as on
/graphs; if the resident has no current device, the last device they wore; if they have never worn one,Patient/<id>. A deleted device's key is its id without a manufacturer. A device in another home does not make the resident404.statsare computed over every reading in the window. - Every graph type in the table below can be charted. Only
heartRateandrespiratoryRatecarry threshold and baseline values. startTimemust not be afterendTime, the window may span at most 24 hours, andstartTimemust not be more than 14 days ago. A request that breaks one of these fails validation.- Readings are charted by when they were observed, or by when Signals stored them when no observed time exists. A reading stamped more than one hour ahead of when Signals stored it is not found by a windowed read.
- A resident with no current device is still charted from the device they last wore. A resident who never wore a device is charted under
Patient/<id>. A graph type with no readings in the window returns{}. - For a combined realtime feed, chart each reading's components (such as heart rate, breathing rate, SpO₂, pulse and perfusion index). Skip a combined point when the graph already has a point at that time.
- Each point carries the limit in force at its own time, so the limit lines step when a limit changes in the window. A new 7-day baseline does not step the line; if the threshold change history cannot be read, points carry the current limits.
- Ovok waits up to 12 seconds for Signals, then returns
503 signals_unavailable(signals_unavailable) withretryAfterSecandRetry-After. The route allows 20 requests per minute per caller and returns429withRetry-Afterabove that limit. When 16 or more realtime reads are already running in the process, it returns503 signals_unavailable(signals_unavailable) before reading. - Results are cached for up to 15 seconds when the response is 128 KB or smaller. Both request times are rounded down to that interval, so a repeated poll can show a window up to 15 seconds old. Larger responses are not cached.
Graph types
Each type charts every Signals reading recorded under one of its codes. The names are the dashboard telemetry's, so
pulse rate by pulse oximetry is pulseRate and never part of heartRate.
graphType | Codes |
|---|---|
heartRate | 8867-4, 43149-4 |
respiratoryRate | 9279-1 |
oxygenSaturation | 59408-5, 2708-6 |
pulseRate | 8889-8 (heart rate by pulse oximetry) |
perfusionIndex | 61006-3, PI (a vendor-specific code, not LOINC) |
bodyTemperature | 8310-5 |
systolicBloodPressure | 8480-6 |
diastolicBloodPressure | 8462-4 |
heartRateVariability | 80404-7 |
Example cURL request
Replace the times with a window that starts within the last 14 days.
curl -X GET \
'https://api.sandbox.ovok.com/v1/slim/trends/realtime?patientId=3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21&startTime=2026-09-28T07:40:00Z&endTime=2026-09-28T07:42:00Z&graphType=heartRate,respiratoryRate' \
-H "Authorization: Bearer ${OVOK_TOKEN}"Successful response
200 — Every reading in the window, by device and graph type
The response is an object keyed by graph type, then by device key. The example is the response to the request above: a two-minute window holding three readings, with no reading for a minute between the first two.
{
"heartRate": {
"Demo-3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b22": {
"dataPoints": [
{
"timestamp": "2026-09-28T07:40:28.000Z",
"timestampMs": 1790581228000,
"data": 63.5,
"maxThreshold": 100,
"minThreshold": 50,
"maxBaseLine": 84,
"minBaseLine": 60
},
{
"timestamp": "2026-09-28T07:41:28.000Z",
"timestampMs": 1790581288000,
"data": 64,
"maxThreshold": 100,
"minThreshold": 50,
"maxBaseLine": 84,
"minBaseLine": 60
},
{
"timestamp": "2026-09-28T07:41:58.000Z",
"timestampMs": 1790581318000,
"data": 64.5,
"maxThreshold": 100,
"minThreshold": 50,
"maxBaseLine": 84,
"minBaseLine": 60
}
],
"stats": {
"average": 64,
"max": 64.5,
"min": 63.5,
"total": 3
}
}
},
"respiratoryRate": {
"Demo-3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b22": {
"dataPoints": [
{
"timestamp": "2026-09-28T07:40:28.000Z",
"timestampMs": 1790581228000,
"data": 14,
"maxThreshold": 24,
"minThreshold": 8,
"maxBaseLine": 18,
"minBaseLine": 12
},
{
"timestamp": "2026-09-28T07:41:28.000Z",
"timestampMs": 1790581288000,
"data": 15,
"maxThreshold": 24,
"minThreshold": 8,
"maxBaseLine": 18,
"minBaseLine": 12
},
{
"timestamp": "2026-09-28T07:41:58.000Z",
"timestampMs": 1790581318000,
"data": 14.5,
"maxThreshold": 24,
"minThreshold": 8,
"maxBaseLine": 18,
"minBaseLine": 12
}
],
"stats": {
"average": 14.5,
"max": 15,
"min": 14,
"total": 3
}
}
}
}| 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 | The resident's series, keyed by the most recently assigned device, last-worn device when none is assigned, or Patient/<id> when the resident never wore a device. A deleted device's key is its id without a manufacturer. |
<graphType>.<deviceKey>.dataPoints | object[] | Every reading in the window, oldest first. No empty points are added between readings. |
<graphType>.<deviceKey>.dataPoints[].timestamp | string (ISO 8601 date-time) | Time of the reading in UTC: when it was observed, or when Signals stored it if no observed time exists. |
<graphType>.<deviceKey>.dataPoints[].timestampMs | integer | Same time in Unix milliseconds. |
<graphType>.<deviceKey>.dataPoints[].data | number | null | Value of the reading, in the unit of the graph type. null when the reading has no numeric value. |
<graphType>.<deviceKey>.dataPoints[].maxThreshold | number | Upper alert limit that applied at this point's time. Omitted when none applies. The value changes when the limit changes. |
<graphType>.<deviceKey>.dataPoints[].minThreshold | number | Lower alert limit that applied at this point's time. Omitted when none applies. The value changes when the limit changes. |
<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>.stats | object | Summary of the readings that have a value. |
<graphType>.<deviceKey>.stats.average | number | null | Mean of the readings that have a value, to 2 decimals. null when no reading has a value or the mean is 0. |
<graphType>.<deviceKey>.stats.max | number | null | Highest value. null when no reading has a value or the value is 0 or less. |
<graphType>.<deviceKey>.stats.min | number | null | Lowest value. null when no reading has a value or the value is 0 or less. |
<graphType>.<deviceKey>.stats.total | integer | Number of readings that have a value. |
Errors
| Status | Meaning |
|---|---|
400 | Your session has no project. |
401 | Bearer token is missing, invalid or expired. |
403 | You are not a practitioner, admin or System Owner, or you lack Organization:read, Device:read, Patient:read or DocumentReference:read. |
404 | No resident with this patientId exists in your project or its sub-projects. |
429 | The caller exceeded 20 realtime requests in a minute. Retry after the Retry-After delay. |
422 | A query parameter fails validation, startTime is after endTime, the window is longer than 24 hours, or startTime is more than 14 days ago. |
503 | Signals did not answer within 12 seconds, or the server already has 16 or more realtime reads running. The body has error: "signals_unavailable" (signals_unavailable) and retryAfterSec; the Retry-After header is set. |
Last updated on