Telemetry

Get device telemetry and alerts

Get device telemetry and alerts using Ovok’s Slim API.

MethodPath
GET/v1/slim/telemetry/:deviceId

Authentication · Access policies

Returns the current telemetry and alerts for one device. Use it to poll the resident detail view.

Auth: bearer token. The caller must be a practitioner, an admin or a System Owner, and needs Device:read. Scope: the caller's project and its sub-projects (from the token). Only devices in that scope are found.

Request

Path parameters

NameTypeRequiredDescription
deviceIdstringYesDevice identifier (for example Demo/3001000) or Device resource id (UUID). Encode the / of an identifier as %2F.

Behaviour

  • deviceId is either the device identifier (for example Demo/3001000) or the Device resource id (a UUID). A UUID is resolved to the identifier.
  • The response deviceId is the identifier the telemetry is keyed by.
  • telemetry and alerts have the same shape as one entry of GET /v1/slim/device/live/telemetry.
  • The device is looked up among all devices of your project and its sub-projects, including devices without a resident.
  • A UUID resolves only for a device in your own project. A device of a sub-project is found by its identifier.
  • Telemetry is read fresh on every request. The device structure is cached and refreshed when you write through the Slim routes.
  • The route returns 503 when the server is at capacity for live reads or the device list cannot be built. Retry shortly.

Example

curl -X GET 'https://api.sandbox.ovok.com/v1/slim/telemetry/3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"

Successful response

200 — Current telemetry and alerts for the device.

{
  "deviceId": "Demo/3001000",
  "telemetry": {
    "active": { "value": true, "ts": 1790581330000 },
    "effectiveHeartRate": { "value": 128, "ts": 1790581315000 },
    "effectiveRespiratoryRate": { "value": 14, "ts": 1790581315000 },
    "effectiveSleepStatus": { "value": "asleep", "ts": 1790581270000 },
    "lastMeasurementTime": { "value": "2026-09-28T07:42:10.000Z", "ts": 1790581330000 },
    "lastActivityTime": { "value": "2026-09-28T07:42:10.000Z", "ts": 1790581330000 },
    "name": { "value": "Demo/3001000", "ts": null },
    "effectiveOxygenSaturation": { "value": null, "ts": null },
    "effectivePulseRate": { "value": null, "ts": null },
    "effectiveSystolicBloodPressure": { "value": null, "ts": null },
    "effectiveDiastolicBloodPressure": { "value": null, "ts": null },
    "effectiveHeartRateVariability": { "value": null, "ts": null },
    "effectivePerfusionIndex": { "value": null, "ts": null },
    "effectiveBodyTemperature": { "value": null, "ts": null }
  },
  "alerts": {
    "heartRate": {
      "alert": true,
      "value": { "measuredValue": 128, "level": "high", "color": "#E5254B" },
      "message": { "signals": { "op": "gt", "threshold": 120, "bound": "max" } },
      "communicationRequestId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b30",
      "observationId": null,
      "color": "#E5254B",
      "state": "alert",
      "updatedAt": "2026-09-28T07:41:55.000Z"
    },
    "respiratoryRate": {
      "alert": false,
      "value": null,
      "message": null,
      "communicationRequestId": null,
      "observationId": null,
      "color": null,
      "state": "normal",
      "updatedAt": null
    },
    "outOfBed": null
  }
}
FieldTypeDescription
deviceIdstringDevice identifier the telemetry is keyed by, for example Demo/3001000.
telemetryobjectCurrent telemetry of the device. Each metric below is an object with value and ts.
telemetry.active.valuebooleantrue while the device is connected. false when the device is marked lost or has sent nothing for more than 10 minutes.
telemetry.active.tsinteger | nullTime of the last activity, in Unix milliseconds.
telemetry.effectiveHeartRate.valuenumber | nullCurrent heart rate in beats per minute, rounded to one decimal. null when the resident is not present in bed or no current reading exists.
telemetry.effectiveHeartRate.tsinteger | nullStart of the measurement window, in Unix milliseconds. null when value is null.
telemetry.effectiveRespiratoryRate.valuenumber | nullCurrent respiratory rate in breaths per minute, rounded to one decimal. null when the resident is not present in bed or no current reading exists.
telemetry.effectiveRespiratoryRate.tsinteger | nullStart of the measurement window, in Unix milliseconds. null when value is null.
telemetry.effectiveSleepStatus.value"disconnected" | "connected" | "away" | "asleep" | "awake" | nullCurrent sleep status. disconnected when the device is inactive. connected when the device is online but presence is unknown. away when the resident is out of bed. asleep or awake when the resident is in bed.
telemetry.effectiveSleepStatus.tsinteger | nullTime the status was set, in Unix milliseconds. For away it is the time the resident left the bed.
telemetry.lastMeasurementTime.valuestring (ISO 8601 date-time)Time of the latest reading from the device.
telemetry.lastMeasurementTime.tsinteger | nullSame time in Unix milliseconds. null when no time is known.
telemetry.lastActivityTime.valuestring (ISO 8601 date-time)Time of the last activity of the device.
telemetry.lastActivityTime.tsinteger | nullSame time in Unix milliseconds.
telemetry.name.valuestringDevice name.
telemetry.name.tsnullAlways null.
telemetry.effectiveOxygenSaturation.valuenumber | nullOxygen saturation in percent. null until the device reports it, and while the resident is not present in bed.
telemetry.effectiveOxygenSaturation.tsinteger | nullStart of the measurement window, in Unix milliseconds. null when value is null.
telemetry.effectivePulseRate.valuenumber | nullPulse rate from pulse oximetry, in beats per minute. It is separate from effectiveHeartRate. null until the device reports it, and while the resident is not present in bed.
telemetry.effectivePulseRate.tsinteger | nullStart of the measurement window, in Unix milliseconds. null when value is null.
telemetry.effectiveSystolicBloodPressure.valuenumber | nullSystolic blood pressure in mmHg. null until the device reports it, and while the resident is not present in bed.
telemetry.effectiveSystolicBloodPressure.tsinteger | nullStart of the measurement window, in Unix milliseconds. null when value is null.
telemetry.effectiveDiastolicBloodPressure.valuenumber | nullDiastolic blood pressure in mmHg. null until the device reports it, and while the resident is not present in bed.
telemetry.effectiveDiastolicBloodPressure.tsinteger | nullStart of the measurement window, in Unix milliseconds. null when value is null.
telemetry.effectiveHeartRateVariability.valuenumber | nullHeart rate variability, in the unit the device reports. null until the device reports it, and while the resident is not present in bed.
telemetry.effectiveHeartRateVariability.tsinteger | nullStart of the measurement window, in Unix milliseconds. null when value is null.
telemetry.effectivePerfusionIndex.valuenumber | nullPerfusion index, in the unit the device reports. null until the device reports it, and while the resident is not present in bed.
telemetry.effectivePerfusionIndex.tsinteger | nullStart of the measurement window, in Unix milliseconds. null when value is null.
telemetry.effectiveBodyTemperature.valuenumber | nullBody temperature in degrees Celsius. null until the device reports it, and while the resident is not present in bed.
telemetry.effectiveBodyTemperature.tsinteger | nullStart of the measurement window, in Unix milliseconds. null when value is null.
alertsobjectAlerts for the device. Every key is always present.
alerts.heartRateobjectHeart rate alert of the resident.
alerts.heartRate.alertbooleantrue while an alert is open for the resident and the current reading still breaches it.
alerts.heartRate.state"alert" | "normal"alert when alert is true, otherwise normal.
alerts.heartRate.colorstring | nullDisplay colour as a hex string, for example #E5254B. null when there is no alert.
alerts.heartRate.valueobject | nullAlert details from Signals. null when there is no alert. The keys below are the ones set today.
alerts.heartRate.value.measuredValuenumberThe reading that breached the limit.
alerts.heartRate.value.level"high" | "low" | nullWhether the reading is above (high) or below (low) the limit. null when unknown.
alerts.heartRate.value.colorstringAlert colour as a hex string.
alerts.heartRate.value.episodeIdstringId of the open Signals episode. Present only for an alert that comes from an episode.
alerts.heartRate.messageobject | nullThe limit that was crossed. null when there is no alert, and for an alert from a Signals episode.
alerts.heartRate.message.signalsobjectThe rule that fired.
alerts.heartRate.message.signals.op"gt" | "lt"gt when the alert fires above the limit, lt when it fires below it.
alerts.heartRate.message.signals.thresholdnumberThe limit that was crossed, for example 120.
alerts.heartRate.message.signals.bound"max" | "min"max when the limit is the upper bound of the range, min when it is the lower bound.
alerts.heartRate.communicationRequestIdstring | nullId of the alert notification. It can stay set after the alert clears. null when there is none, and for an alert from a Signals episode.
alerts.heartRate.observationIdstring | nullReserved. Always null today.
alerts.heartRate.updatedAtstring (ISO 8601 date-time) | nullTime the alert was last updated.
alerts.respiratoryRateobjectRespiratory rate alert of the resident.
alerts.respiratoryRate.alertbooleantrue while an alert is open for the resident and the current reading still breaches it.
alerts.respiratoryRate.state"alert" | "normal"alert when alert is true, otherwise normal.
alerts.respiratoryRate.colorstring | nullDisplay colour as a hex string, for example #E5254B. null when there is no alert.
alerts.respiratoryRate.valueobject | nullAlert details from Signals. null when there is no alert. The keys below are the ones set today.
alerts.respiratoryRate.value.measuredValuenumberThe reading that breached the limit.
alerts.respiratoryRate.value.level"high" | "low" | nullWhether the reading is above (high) or below (low) the limit. null when unknown.
alerts.respiratoryRate.value.colorstringAlert colour as a hex string.
alerts.respiratoryRate.value.episodeIdstringId of the open Signals episode. Present only for an alert that comes from an episode.
alerts.respiratoryRate.messageobject | nullThe limit that was crossed. null when there is no alert, and for an alert from a Signals episode.
alerts.respiratoryRate.message.signalsobjectThe rule that fired.
alerts.respiratoryRate.message.signals.op"gt" | "lt"gt when the alert fires above the limit, lt when it fires below it.
alerts.respiratoryRate.message.signals.thresholdnumberThe limit that was crossed, for example 24.
alerts.respiratoryRate.message.signals.bound"max" | "min"max when the limit is the upper bound of the range, min when it is the lower bound.
alerts.respiratoryRate.communicationRequestIdstring | nullId of the alert notification. It can stay set after the alert clears. null when there is none, and for an alert from a Signals episode.
alerts.respiratoryRate.observationIdstring | nullReserved. Always null today.
alerts.respiratoryRate.updatedAtstring (ISO 8601 date-time) | nullTime the alert was last updated.
alerts.outOfBedobject | nullThe resident's open out-of-bed episode, or null when there is none.
alerts.outOfBed.outOfBedbooleanAlways true when the object is present.
alerts.outOfBed.communicationRequestIdstringId of the out-of-bed notification.
alerts.outOfBed.sinceTimestring (ISO 8601 date-time)Time the resident left the bed. It stays the same while the episode lasts.

Errors

StatusMeaning
401Bearer token is missing, invalid or expired.
403You are not a practitioner, admin or System Owner, you lack Device:read, your session has no project, or you cannot access the project.
404No telemetry or alerts exist for this device in your project.
503The server is at capacity for live reads (the body has error: "live_reads_over_capacity" (live_reads_over_capacity) and retryAfterSec, and the Retry-After header is set), the device list cannot be built right now (no Retry-After), or the access policy cannot be read. Retry shortly.

Last updated on

On this page