Device Health Issues (Beta)
The Device Health Issues API surfaces health problems detected on telematics devices across your assets, so you can build dashboards, alerts, and maintenance workflows before data gaps or connectivity issues affect operations. The API is read-only: you can query issues that Trackunit has already detected, but you cannot create, update, or resolve them through this API.
Issue categories
Each issue belongs to one of four categories that group related device health problems:
- Install and configuration — problems related to device setup or configuration, such as missing CAN data configuration or unusual operating hours.
- Coverage — connectivity problems, including low GPS or cellular coverage.
- Device battery — power-related problems, such as low device input or battery voltage.
- Non-reporting device — cases where expected data is not being received from the device.
Within each category, issues are further classified by a specific type (for example, LOW_GPS_COVERAGE or DATA_NOT_RECEIVED). Each issue also has a criticality level (CRITICAL, LOW, or UNKNOWN) indicating its severity.
Issue lifecycle
Issues move between two states: OPEN and RESOLVED.
An issue is created in the OPEN state when Trackunit detects a health problem on a device.
It includes a createdAt timestamp and is linked to the affected asset and device.
When the underlying condition is no longer detected, the issue transitions to RESOLVED and a resolvedAt timestamp is set.
Querying issues
The API exposes three read endpoints for retrieving issues:
- Get issues — list issues across your fleet, filtered by state.
- Get issues by asset — list issues for a specific asset.
- Get issue by id — fetch a single issue by its identifier.
The fleet-wide and per-asset list endpoints support pagination and sorting through the following query parameters:
| Parameter | Required | Description |
|---|---|---|
state | Yes (fleet-wide list only) | Filter by issue state: OPEN or RESOLVED. |
page | No | Zero-based page index. Default: 0. |
size | No | Number of issues per page. Default: 20. |
sort | No | Sort by an issue property. Use property or +property for ascending order, -property for descending order (for example, -type or -createdAt). |
Example request listing open issues, sorted by type descending:
GET https://iris.trackunit.com/api/device-health-issues/v1beta1/issues?state=OPEN&page=0&size=200&sort=-type
Paginated responses include a content array of issues plus metadata such as totalElements and totalPages.
Use page and size to walk through large result sets.
Constraints
- The Device Health Issues API is read-only. It exposes issues detected by Trackunit; clients cannot submit or manage issues through this API.
- Issues are detected automatically based on device telemetry and configuration. The API reflects what the platform has identified—it does not accept external health signals or manual issue creation.