Devices

List live telemetry and alerts by device

List live telemetry and alerts by device using Ovok’s Slim API.

MethodPath
GET/v1/slim/device/live/telemetry

Authentication · Access policies

Returns the telemetry and alerts for one page of live devices, keyed by device. Use it to poll the values on a page you already loaded with GET /v1/slim/device/live.

Auth: bearer token. The caller must be a practitioner, an admin or a System Owner, and needs search and read on Patient, Device, Location, Observation and Organization. Scope: the caller's project (from the token).

Request

Query parameters

NameTypeRequiredDescription
pageintegerNoZero-based page number. Default 0, minimum 0.
countintegerNoRows per page. Default 20, minimum 1, maximum 100.
sortBy"locationName" | "patientName" | "patientNickname" | "organizationName" | "effectiveHeartRate" | "effectiveRespiratoryRate" | "effectiveSleepStatus" | "admissionDate" | "dischargeDate"NoSort column. Default locationName.
orderBy"ASC" | "DESC"NoSort direction. Upper case only. Default ASC.
searchstringNoFuzzy match on resident nickname and name, location name, zone name, and device name, identifier and serial. Trimmed, at least 1 character.
deviceIdstringNoKeep only this device, matched against the device identifier.
organizationIdstringNoA zone id, assigned or unassigned. A zone id also matches devices in its child zones.
effectiveSleepStatus"disconnected" | "connected" | "awake" | "away" | "asleep"NoKeep devices in this sleep status.
residentState"active" | "discharged-recent" | "discharged" | "archived"NoAccepted and ignored.
includeUnassignedbooleanNotrue also returns devices without a resident. Any other value is false. Default false.

Behaviour

  • Takes the same query parameters as GET /v1/slim/device/live and selects the same page of devices in the same order.
  • telemetry and alerts are keyed by the device identifier (for example Sleepiz/3001000), not by the Device resource id.
  • alerts has an entry for every device on the page. telemetry has an entry only for devices with telemetry.
  • total, page and count describe the page, as on /live.
  • Telemetry is read fresh on every request.
  • 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/device/live/telemetry?page=0&count=20' \
  -H "Authorization: Bearer ${OVOK_TOKEN}"

Successful response

200 — Telemetry and alerts for one page of live devices.

{
  "total": 1,
  "page": 0,
  "count": 20,
  "telemetry": {
    "Demo/1000001": {
      "active": { "value": true, "ts": 1790000000000 },
      "effectiveHeartRate": { "value": 62, "ts": 1789999400000 },
      "effectiveRespiratoryRate": { "value": 14, "ts": 1789999400000 },
      "effectiveSleepStatus": { "value": "asleep", "ts": 1789998000000 },
      "lastMeasurementTime": { "value": "2026-10-09T08:50:00.000Z", "ts": 1789999800000 },
      "lastActivityTime": { "value": "2026-10-09T08:53:20.000Z", "ts": 1790000000000 },
      "name": { "value": "Demo/1000001", "ts": null },
      "effectiveOxygenSaturation": { "value": 97, "ts": 1789999400000 },
      "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": {
    "Demo/1000001": {
      "heartRate": { "alert": false, "value": null, "message": null, "communicationRequestId": null, "observationId": null, "color": null, "state": "normal", "updatedAt": null },
      "respiratoryRate": { "alert": false, "value": null, "message": null, "communicationRequestId": null, "observationId": null, "color": null, "state": "normal", "updatedAt": null },
      "outOfBed": null
    }
  }
}
FieldTypeDescription
totalintegerNumber of devices after filtering, across all pages.
pageintegerPage number of this response.
countintegerPage size of this response.
telemetryobjectTelemetry keyed by device identifier. A device with no telemetry has no entry.
telemetry.<identifier>objectLatest live telemetry of the device. Every metric in it is an object with value and ts.
telemetry.<identifier>.<metric>.tsinteger | nullTime of the value in epoch milliseconds.
telemetry.<identifier>.activeobjectvalue is true when the device is connected. A device with no activity for 10 minutes is false.
telemetry.<identifier>.effectiveHeartRateobjectvalue is the heart rate in beats per minute with one decimal, or null when no resident is in bed or there is no reading.
telemetry.<identifier>.effectiveRespiratoryRateobjectvalue is the respiratory rate in breaths per minute with one decimal, or null.
telemetry.<identifier>.effectiveSleepStatusobjectvalue is "asleep", "awake", "away", "connected" or "disconnected".
telemetry.<identifier>.lastMeasurementTimeobjectvalue is an ISO 8601 time string.
telemetry.<identifier>.lastActivityTimeobjectvalue is an ISO 8601 time string.
telemetry.<identifier>.nameobjectvalue is the device name. ts is null.
telemetry.<identifier>.effectiveOxygenSaturationobjectvalue is a number or null.
telemetry.<identifier>.effectivePulseRateobjectvalue is a number or null.
telemetry.<identifier>.effectiveSystolicBloodPressureobjectvalue is a number or null.
telemetry.<identifier>.effectiveDiastolicBloodPressureobjectvalue is a number or null.
telemetry.<identifier>.effectiveHeartRateVariabilityobjectvalue is a number or null.
telemetry.<identifier>.effectivePerfusionIndexobjectvalue is a number or null.
telemetry.<identifier>.effectiveBodyTemperatureobjectvalue is a number in degrees Celsius or null.
alertsobjectAlerts keyed by device identifier. Every device on the page has an entry.
alerts.<identifier>objectCurrent alerts of the resident on the device.
alerts.<identifier>.heartRateobjectHeart rate alert.
alerts.<identifier>.heartRate.alertbooleantrue while the alert is active.
alerts.<identifier>.heartRate.state"alert" | "normal"alert while the alert is active, otherwise normal.
alerts.<identifier>.heartRate.colorstring | nullAlert color. null when there is no alert.
alerts.<identifier>.heartRate.valueobject | nullAlert details as recorded by Signals. null when there is no alert.
alerts.<identifier>.heartRate.messageobject | nullAlert message as recorded by Signals. null when there is no alert.
alerts.<identifier>.heartRate.communicationRequestIdstring | nullId of the alert's CommunicationRequest.
alerts.<identifier>.heartRate.observationIdstring | nullId of the Observation that raised the alert.
alerts.<identifier>.heartRate.updatedAtstring | nullWhen the alert last changed.
alerts.<identifier>.respiratoryRateobjectRespiratory rate alert, with the same fields as alerts.<identifier>.heartRate.
alerts.<identifier>.outOfBedobject | nullThe active out-of-bed episode of the resident. null when there is none or an open episode has no start time.
alerts.<identifier>.outOfBed.outOfBedtrueAlways true.
alerts.<identifier>.outOfBed.communicationRequestIdstringId of the Signals episode.
alerts.<identifier>.outOfBed.sinceTimestringWhen the resident left the bed, as an ISO 8601 time string.

Errors

StatusMeaning
401Bearer token is missing, invalid or expired.
403You are not a practitioner, admin or System Owner, you lack search or read on Patient, Device, Location, Observation or Organization, your session has no project, or you cannot access the project.
422A query parameter fails validation.
503The server is at capacity for live reads, or the device list cannot be built and no earlier complete list exists. Retry after the number of seconds in the Retry-After header.

Last updated on

On this page