Device network metrics
/api/v1/integrations/devices/{device_id}/network/{resource}DevicesReturns network time-series metrics for a device from Amazon Timestream (historical_metrics). The same route handles five resources; choose one via the resource path segment: latency, packet-loss, jitter, metrics, or lte. The account is resolved from the Bearer token; the device must belong to that account.
Invalid interval or time_bucket (or unknown query parameters) returns 400 with success: false, a text message describing the validation errors, and request_id when available.
Bearer access tokenapplication/jsonPath parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
device_id | string | Yes | Device identifier used by the integration API (often the device serial; align with Get Device). |
resource | string | Yes | Metric family to query. Must be exactly one of the values in the table below. |
resource values
| resource | Description |
|---|---|
latency | Network latency measurements over the requested window. |
packet-loss | Packet loss metrics over the requested window. |
jitter | Jitter metrics over the requested window. |
metrics | Comprehensive network metrics for the device. |
lte | LTE radio metrics per time bucket: RSSI (dBm) and CSQ (0–30) from `measure_name = stats` / `subsystems = lte`, using the same scaling as internal historical-metrics processing. |
Any other resource value returns 404 with success: false and a message listing the allowed values (latency, packet-loss, jitter, metrics, lte).
lte row fields
Each element of data for resource=lte is one time bucket:
| Field | Type | Description |
|---|---|---|
time_bucket | string | Bucket start (Timestream `BIN(time, time_bucket)`). |
interface | string | Subsystem, e.g. `lte`. |
avg_rssi | number | Mean RSSI in dBm for the bucket (after scaling). |
min_rssi | number | Minimum RSSI in the bucket. |
max_rssi | number | Maximum RSSI in the bucket. |
avg_csq | number | Mean CSQ on 0–30 scale for the bucket. |
min_csq | number | Minimum CSQ in the bucket. |
max_csq | number | Maximum CSQ in the bucket. |
If a bucket has no valid samples, min/max/avg fields are 0.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
interval | string | No | Lookback window for metrics. Default 24h. Must match ^\d+[hd]$ (hours or days), e.g. 1h, 24h, 7d. |
time_bucket | string | No | Aggregation bucket size. Default 1h. Must match ^\d+[mhd]$ (minutes, hours, or days), e.g. 15m, 1h, 1d. Same field accepts query aliases bucket or time_bucket_size. |
probe_target | string | No | Optional probe target (e.g. 8.8.8.8) for advance-monitoring series. Default omits the filter. Ignored when resource=lte. |
Headers
| Header | Value | Required |
|---|---|---|
Authorization | Bearer <access_token> | Yes |
Responses
On success, the handler returns an ApiResponse payload (via model_dump) including data as an array of rows for that resource, plus request_id.
| HTTP | Description |
|---|---|
| 200 | `success: true`, `data` = array of `NetworkLatencyMetricsRow` | `NetworkPacketLossMetricsRow` | `NetworkJitterMetricsRow` | `NetworkComprehensiveMetricsRow` | `NetworkLteMetricsRow` (depending on `resource`), `request_id` set. |
| 400 | Bad request — invalid `interval` / `time_bucket`, or extra query parameters (`success: false`, `text`, `request_id`). |
| 401 | Unauthorized — invalid or missing Bearer token. |
| 404 | Unknown `resource`, unresolved account/device, or service reported not-found (`success: false`, `text`, `request_id`). |
| 500 | Service or Timestream error (`success: false`, `text`, `request_id`). |
Examples
Defaults match the API model: interval=24h, time_bucket=1h if you omit query params.