Trends

Get realtime trends graphs

Get realtime trends graphs using Ovok’s Slim API.

MethodPath
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

NameTypeRequiredDescription
patientIdstring (uuid)YesResident (Patient) id.
startTimestring (ISO 8601 date-time)YesStart 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.
endTimestring (ISO 8601 date-time)YesEnd of the window, in UTC (ends in Z). At most 24 hours after startTime.
graphTypestring (comma-separated)YesGraph 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 resident 404. stats are computed over every reading in the window.
  • Every graph type in the table below can be charted. Only heartRate and respiratoryRate carry threshold and baseline values.
  • startTime must not be after endTime, the window may span at most 24 hours, and startTime must 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) with retryAfterSec and Retry-After. The route allows 20 requests per minute per caller and returns 429 with Retry-After above that limit. When 16 or more realtime reads are already running in the process, it returns 503 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.

graphTypeCodes
heartRate8867-4, 43149-4
respiratoryRate9279-1
oxygenSaturation59408-5, 2708-6
pulseRate8889-8 (heart rate by pulse oximetry)
perfusionIndex61006-3, PI (a vendor-specific code, not LOINC)
bodyTemperature8310-5
systolicBloodPressure8480-6
diastolicBloodPressure8462-4
heartRateVariability80404-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
      }
    }
  }
}
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>objectThe 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>.dataPointsobject[]Every reading in the window, oldest first. No empty points are added between readings.
<graphType>.<deviceKey>.dataPoints[].timestampstring (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[].timestampMsintegerSame time in Unix milliseconds.
<graphType>.<deviceKey>.dataPoints[].datanumber | nullValue of the reading, in the unit of the graph type. null when the reading has no numeric value.
<graphType>.<deviceKey>.dataPoints[].maxThresholdnumberUpper alert limit that applied at this point's time. Omitted when none applies. The value changes when the limit changes.
<graphType>.<deviceKey>.dataPoints[].minThresholdnumberLower alert limit that applied at this point's time. Omitted when none applies. The value changes when the limit changes.
<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>.statsobjectSummary of the readings that have a value.
<graphType>.<deviceKey>.stats.averagenumber | nullMean 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.maxnumber | nullHighest value. null when no reading has a value or the value is 0 or less.
<graphType>.<deviceKey>.stats.minnumber | nullLowest value. null when no reading has a value or the value is 0 or less.
<graphType>.<deviceKey>.stats.totalintegerNumber of readings that have a value.

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 Organization:read, Device:read, Patient:read or DocumentReference:read.
404No resident with this patientId exists in your project or its sub-projects.
429The caller exceeded 20 realtime requests in a minute. Retry after the Retry-After delay.
422A query parameter fails validation, startTime is after endTime, the window is longer than 24 hours, or startTime is more than 14 days ago.
503Signals 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

On this page