Skip to content

Device Heartbeat

APIs to retrieve information about device's heartbeat which contains the last seen details.

Operations

Get heartbeat of a device which contains last seen information
Stable

Request

Retrieves the last-seen heartbeat record for a single device, including its most recent check-in timestamp.

Returns the device UUID, the last-seen timestamp, and a legacy status flag indicating whether the device was seen within the last 30 minutes (1) or not (0).

About Get Device Heartbeat (v0)

The heartbeat endpoint provides a lightweight alternative to a full device fetch when only connectivity recency is needed. The status field is a legacy binary indicator (1 = seen in the last 30 minutes, 0 = not seen) and should not be used as the sole signal for device availability in new integrations — use the timestamp directly for more precise evaluation. For bulk heartbeat queries across all devices within a time window, use /api/v2/heartbeat/.

Key Fields

device_id — UUID of the device

timestamp — ISO 8601 datetime of the device's last check-in

status — Legacy field: 1 if last seen within 30 minutes, 0 otherwise

Common Use Cases

Confirming a specific device is online before triggering a remote operation

Displaying last-seen timestamps in a device monitoring dashboard

Lightweight polling loop to detect when a device comes back online

Best Practices

Use timestamp rather than status for precision — status is a legacy 30-minute binary bucket and is not suitable for finer-grained availability logic

For checking connectivity across many devices in a time window, use /api/v2/heartbeat/ instead

Avoid polling this endpoint at high frequency; prefer event-driven or scheduled checks

Security
device_apiKey
Path
idstring, (uuid)required

ID of the device

cURL
curl -i -X GET \
  'https://api.esper.io/_mock/openapi/device/v0/heartbeat/{id}/' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Last seen details of the device

Bodyapplication/json
codeinteger
messagestring
contentobject(device_EsperDeviceHeartbeat)
Response
{
  "code": 0,
  "message": "string",
  "content": {
    "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
    "timestamp": "2019-08-24T14:15:22Z",
    "status": 0
  }
}