GET /v2/devices/{device_id}/telemetry

Returns telemetry data for a specific device. Results are sorted by device time ascending. Supports cursor-based pagination.

Request

curl -k "https://api.illumience.com:11443/v2/devices/{device_id}/telemetry?from=1709251200&to=1709337600&limit=100" \
  -H "Authorization: Bearer <api_key>"

Path Parameters

Parameter	Type	Description
device_id	integer	device identifier, can be found by calling /v2/devices

Query Parameters

Parameter	Required	Type	Default	Description
from	Yes	integer	—	Start time as Unix timestamp (seconds)
to	Yes	integer	—	End time as Unix timestamp (seconds)
limit	No	integer	1000	Maximum number of records (1 - 10,000)
next_cursor	No	integer	—	Pagination cursor from a previous response

Validation Rules

• from and to are required

• to must be greater than from

• Maximum time range is 1 day (86,400 seconds)

• limit is clamped to the range 1 - 10,000

Response 200 OK

{
  "total": 100,
  "has_more": true,
  "next_cursor": 1709308801.0,
  "pings": [
    {
      "device_id": 4521,
      "cloud_unixtime": 1709251260.0,
      "device_unixtime": 1709251260.0,
      "device_date": "2024-03-01",
      "device_time": "00:01:00",
      "device_datetime_tz": "2024-03-01T02:01:00+02:00",
      "data": {
        "bv": 52.1,
        "bc": 3.2,
        "bt": 25.0,
        "p1v": 38.5,
        "p1c": 8.1,
        "l1v": 230.0,
        "l1c": 2.5
      },
      "statuses": {
        "l1": { "en": true, "lvd": false },
        "batt": { "en": true, "batt_charging_en": true }
      }
    }
  ]
}

Response Fields

Field	Type	Description
total	integer	Number of pings in this page
has_more	boolean	true if more records exist beyond this page
next_cursor	integer or null	Pass this value as next_cursor in the next request to fetch the next page. null when there are no more results.
pings	array	List of telemetry ping objects

Ping Object:

Field	Type	Description
device_id	integer	Numeric device identifier
cloud_unixtime	float	Timestamp when the cloud received the ping
device_unixtime	float	Timestamp from the device's internal clock
device_date	string	Date string from device (YYYY-MM-DD)
device_time	string	Time string from device (HH:MM:SS)
device_datetime_tz	string	ISO 8601 datetime with timezone offset
data	object	Telemetry readings (see Data Fields below)
statuses	object	Device status flags (dynamic structure)

Pagination

The API uses cursor-based pagination anchored on device_unixtime:

1. Make the initial request with from and to.

2. If has_more is true, take the next_cursor value from the response.

3. Pass it as the next_cursor query parameter in the next request (keep the same from, to, and limit).

4. Repeat until has_more is false.

Errors

Code	Cause
400	Missing from/to, invalid range, invalid ObjectId
404	Device not found or not owned by customer