Skip to content

Get list of heartbeat for all devices
Stable

Request

Retrieves heartbeat records for all devices whose last-seen timestamp falls within a specified date-time range.

Requires last_seen_gt and last_seen_lt query parameters to define the time window, and optionally filters by platform. Returns a paginated list of EsperDeviceHeartbeat records, each containing device UUID, last-seen timestamp, and a legacy status flag.

About List Device Heartbeats (V2)

This endpoint enables bulk connectivity queries across the entire device fleet, useful for fleet health monitoring, SLA reporting, and identifying devices that have gone silent over a defined period. The required time window filters mean queries are always bounded, preventing inadvertent large data pulls. The platform filter can be used to narrow results to a specific OS family. As with the single-device heartbeat endpoint, the status field is a legacy 30-minute binary indicator; use timestamp values directly for precision analysis.

Key Query Parameters

last_seen_gt (required) — Start of the time window in ISO 8601 format (e.g., 2024-01-01T00:00:00Z)

last_seen_lt (required) — End of the time window in ISO 8601 format

platform — Optional platform filter: ANDROID, APPLE, LINUX, or WINDOWS

limit / offset — Pagination controls

Common Use Cases

Generating daily fleet health reports showing which devices checked in during the past 24 hours

Identifying devices that have gone silent (not seen within a defined window) for incident response

Producing SLA-aligned uptime evidence for specific device cohorts

Best Practices

Keep the time window reasonably narrow for large fleets to limit result set size and response latency

Use platform to scope queries when platform-specific reporting is needed

Use timestamp from each result record for precise analysis; do not rely on the legacy status field for business logic

Workflow

Define the time window using last_seen_gt and last_seen_lt (both required)

Optionally add platform to narrow results

Paginate through results; devices appearing in the result set were seen within the window

Security
device_apiKey
Query
last_seen_gtstring, (date-time)required

Specify the starting date and time for device lookup in the format (2023-08-29T00:00:00Z).

Example:last_seen_gt=2023-08-29T00:00:00Z
last_seen_ltstring, (date-time)required

Specify the end date and time for device lookup in the format (2023-08-30T00:00:00Z).

Example:last_seen_lt=2023-08-30T00:00:00Z
platformstring

platform of the device

Enum:"ANDROID""APPLE""LINUX""WINDOWS"
limitinteger
offsetinteger
cURL
curl -i -X GET \
  'https://api.esper.io/_mock/openapi/v2/heartbeat/?last_seen_gt=2023-08-29T00%3A00%3A00Z&last_seen_lt=2023-08-30T00%3A00%3A00Z&platform=ANDROID&limit=0&offset=0' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Last seen details of the device

Bodyapplication/json
codeinteger
messagestring
contentobject(device_DeviceLastSeen)
Response
{
  "code": 0,
  "message": "string",
  "content": {
    "count": 0,
    "prev": "string",
    "next": "string",
    "results": [ … ]
  }
}