Telemetry API

Telemetry API provides HTTP API to request telemetry.

Get Latest Telemetry CloudGateway

GET /v3/telemetry/latest

Returns the latest values of specified telemetry attributes.

Request

$ curl http://api.enapter.com/v3/telemetry/latest -X GET -G \
  -H 'X-Enapter-Auth-Token: {ACCESS_TOKEN}' \
  -d 'devices[123e4567-e89b-12d3-a456-426614174000]=voltage,uptime'

Query Parameters

devicesobjectrequired

device's keys are device IDs, and the values are a list of comma-separated telemetry attributes.

relevance_intervalduration stringdefault: 30s

Time window during which a telemetry value should be considered valid or up to date.

Response

{
  "telemetry": {
    "123e4567-e89b-12d3-a456-426614174000": {
      "voltage": {
        "value": 2,
        "timestamp": 1662593249
      },
      "uptime": {
        "value": 12345,
        "timestamp": 1662593249
      }
    }
  }
}

If some attributes were not acquired, you will receive an explanation in the warning field. For example,

{
  "telemetry": {
    "123e4567-e89b-12d3-a456-426614174000": {
      "voltage": {
        "value": 2,
        "timestamp": 1662593249
      },
      "amperage": {
        "warning": "Telemetry attribute is not found.",
      }
    }
  }
}

telemetryobject

Telemetry object keys are requested device IDs and values are DeviceTelemetry object.

DeviceTelemetryobject

DeviceTelemetry object kesy are requested telemetry attributes and values are DeviceTelemetryValue object.

DeviceTelemetryValueobject

DeviceTelemetryValue.valuenumber, boolean, string, array of strings

The value of requested telemetry attribute.

DeviceTelemetryValue.timestampinteger

The timestamp of the most relevant value of requested telemetry attribute.

DeviceTelemetryValue.warningstring

The warning message if telemetry attribute was not retrived.

Query Time Series CloudGateway

POST /v3/telemetry/query_timeseries

Returns time series - a sequence of measurements, ordered in time.

Request

$ curl http://api.enapter.com/v3/telemetry/query_timeseries -X POST \
  -H 'X-Enapter-Auth-Token: {ACCESS_TOKEN}' \
  -H 'Accept: text/csv' \
  -d '{
    "from": "2025-09-11T00:00:00Z",
    "to": "2025-09-11T00:01:00Z",
    "aggregation": "avg",
    "granularity": "1s",
    "telemetry": [{
      "device": "123e4567-e89b-12d3-a456-426614174000",
      "attribute": "voltage",
    }]
  }'

Required header

The response header Accept is mandatory and must equal text/csv.

Body Parameters

The request body is written in a query language based on JSON according to the schema.

fromnumber, stringrequired

Start of the time frame. Either a number containing a Unix timestamp or a string in RFC 3339 format.

tonumber, stringrequired

End of the time frame. Either a number containing a Unix timestamp or a string in RFC 3339 format.

aggregationstring

Time bucket aggregation function. Can be overridden for each individual telemetry attribute.

Currently supported functions:

• auto — select either avg or last depending on the data type;
• avg — calculate arithmetic mean;
• last — use the last value;
• min — use the minimum value;
• max — use the maximum value;
• bool_or — use the logical or operation between values (true if any true is present, false otherwise).

granularityduration string

Time bucket interval.

gap_fillingobject

Gap-filling settings, an instance of the GapFilling object. Can be overridden for each individual telemetry attribute.

GapFilling.methodstring

Gap-filling method. Currently, two gap-filling methods are supported:

1. locf — fill in missing values by last observation carried forward;
2. interpolation - fill in missing values by linear interpolation.

GapFilling.look_aroundduration string

Interval in the past to look for values outside of the time range specified.

sitestring,object

The site can be provided in two forms: a site_id string or a SiteLabelMatcher object.

SiteLabelMatcherobject

SiteLabelMatcher allows selecting sites in different ways.

SiteLabelMatcher.idstring,object

The id can be provided in two forms: a string or a SiteIdMatcher object.

SiteIdMatcherobject

SiteIdMatcher.is_equal_tostring

The concrete value for id.

SiteIdMatcher.matches_regexpstring

The regular expression to match the id.

telemetryarray of objects

The telemetry contains an array of Telemetry objects.

Telemetryobject

The Telemetry object describes which telemetry attributes from which devices should be retrieved and how to aggregate the values.

Telemetry.devicestring,array of strings,object,array of objects

The device can be specified as string(s) or DeviceLabelMatcher object(s). In string(s) form, device contains a single device ID or an array of device IDs. In DeviceLabelMatcher object(s) — a single DeviceLabelMatcher object or an array of DeviceLabelMatcher objects.

DeviceLabelMatcherobject

DeviceLabelMatcher allows selecting devices in different ways.

DeviceLabelMatcher.idstring,object

The id can be provided in two forms: a string or a DeviceIdMatcher object.

DeviceIdMatcherobject

DeviceIdMatcher.is_equal_tostring

The concrete value for id.

DeviceIdMatcher.matches_regexpstring

The regular expression to match the id.

DeviceLabelMatcher.slugstring,object

The slug can be provided in two forms: a string or a DeviceSlugMatcher object.

DeviceSlugMatcherobject

DeviceSlugMatcher.is_equal_tostring

The concrete value for slug.

DeviceSlugMatcher.matches_regexpstring

The regular expression to match the slug.

Telemetry.attributestring,object

The telemetry attribute can be provided in two forms: a string with a concrete attribute name or an AttributeLabelMatcher object.

The telemetry attribute name should match the one specified in the blueprint manifest for this device.

AttributeLabelMatcherobject

AttributeLabelMatcher allows selecting telemetry attributes in different ways.

AttributeLabelMatcher.namestring,object

The name can be provided in two forms: a string or a AttributeNameMatcher object.

AttributeNameMatcherobject

AttributeNameMatcher.is_equal_tostring

The concrete value for name.

AttributeNameMatcher.matches_regexpstring

The regular expression to match the name.

telemetry.aggregationstring

Time bucket aggregation function. Overrides global aggregation settings. Required if global aggregation settings are not set.

telemetry.gap_fillingobject

Gap-filling settings. Overrides global gap_filling settings.

Response

Sample response (200 OK)

ts,telemetry=voltage device=123e4567-e89b-12d3-a456-426614174000 aggregation=auto granularity=1s gap_filling_method=none gap_filling_look_around=0s
1665446400,4.3087
1665446410,4.3556
1665446419,4.3712

First timestamp in response

The first timestamp in the response cannot be less than from. It can be equal to from if the requested telemetry has data exactly at the from timestamp, which is the case in most scenarios.

However, it can sometimes be unclear why the first timestamp is not equal to from when the granularity is not 1s.

When you provide granularity, all timestamps are aligned to specific intervals, independent of the from value. The default alignment is midnight on January 3, 2000, for granularities that do not include a month or year interval, and midnight on January 1, 2000, for month and year granularities.

Therefore, the first timestamp will be the nearest aligned timestamp that is greater than or equal to from.

A successful response is telemetry data in CSV format. The first row of the response is the CSV header. The first column is always ts — a Unix timestamp. Other columns contain a space-separated list of key=value pairs describing the parameters used to calculate the time series in the column.

Possible header keys:

• telemetry — telemetry attribute name;
• device — device ID;
• aggregation — time bucket aggregation function;
• granularity — time bucket interval;
• gap_filling_method — gap-filling method;
• gap_filling_look_around — gap-filling interval.

Each row after the first one represents one time series measurement at a specific time from the first column.

The HTTP header Content-Type is text/csv. The HTTP header X-Enapter-Timeseries-Data-Types contains a comma-separated list of types for each data column. The first column is always a timestamp, so this header describes types starting from the second. Possible types are float, integer, string, boolean.

X-Enapter-Timeseries-Data-Types: float,integer,boolean

Duration String Format

A duration string is a sequence of decimal numbers, each with an optional fraction and a unit suffix, such as 1s, 1.5m, or 2h45m. Valid time units are ns (nanosecond), us (microsecond), ms (millisecond), s (second), m (minute), h (hour), d (day), y (year).