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:

Make the initial request with from and to.
If has_more is true, take the next_cursor value from the response.
Pass it as the next_cursor query parameter in the next request (keep the same from, to, and limit).
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