跳至主要内容

Get aggregated data stream values

GET 
/api/v1/orgs/{orgId}/devices/{deviceId}/data-streams/{dataStreamId}/aggregate

Compute one or more aggregate values over a time range in fixed-width buckets (period), optionally with an overlapping slidingStep.

Parameters

  • deviceId (string, required): Unique ID of the device. Example: 74fe488d5d35
  • dataStreamId (Guid, required): Unique ID of the data stream. Example: 3a217ee3-fb2c-617b-6ff6-7257537afade
  • startTime (DateTime, required): Window start, ISO 8601 date-time. Example: 2026-09-01T00:00:00Z
  • endTime (DateTime, required): Window end, ISO 8601 date-time. Example: 2026-09-02T00:00:00Z
  • period (string, required): Bucket width for the time-windowed grouping, as an ISO 8601 duration.
  • slidingStep (string, optional): Sliding step between consecutive buckets, as an ISO 8601 duration; defaults to period (non-overlapping, contiguous buckets) when omitted. Must not be smaller than period.
  • function (string[], required): One or more aggregate functions to compute. Accepts either repeated query parameters (function=COUNT&function=MAX_VALUE) or a single comma-separated value (e.g. function=COUNT,MAX_VALUE); the two forms may also be mixed. The complete set of valid values, matched case-insensitively, is: SUM, COUNT, AVG, EXTREME, MAX_VALUE, MIN_VALUE, FIRST_VALUE, LAST_VALUE, MAX_TIME, MIN_TIME. No other value is accepted. Each requested function becomes a field on every data row it has a value for, keyed by the lowercase form of the same name (e.g. requesting MAX_VALUE produces the field max_value). The request and response spellings differ only in case.

Numerical functions (SUM, AVG, EXTREME, MAX_VALUE, MIN_VALUE) require the data stream's dataType to be one of the three numeric types: double, integer, long. Requesting a Numerical function against a data stream whose dataType is any other value (boolean, string, application/json, application/octet-stream, image/png, image/jpeg, image/jpg, data-pack, blob) rejects the whole call with 422. The remaining functions (COUNT, FIRST_VALUE, LAST_VALUE, MAX_TIME, MIN_TIME) are Universal and work against any dataType.

Response Fields:

  • deviceId (string): Device unique ID the aggregated values belong to.
  • dataStreamId (Guid): Unique ID of the data stream the aggregated values belong to.
  • dataType (string): Data type of the underlying stream values.
  • values (object): One entry per requested function, keyed by its lowercase name (e.g. avg, max_value); a function with no buckets in range is omitted. Each entry is an array of:
    • timestamp (long): Bucket start time as a Unix epoch timestamp in milliseconds (UTC), not an ISO 8601 date-time string. Example: 1788220800000 is 2026-09-01T00:00:00Z.
    • value: Computed value for the bucket (a number, except FIRST_VALUE/LAST_VALUE against a non-numeric stream, which carry that stream's native string/boolean value).

Responses

  • 200 OK: Returns data, one row per time bucket ordered by timestamp, each row carrying one field per requested function that has a value for that bucket, alongside its timestamp.
  • 400 Bad Request: Missing or malformed time range, period, or slidingStep (not parseable as ISO 8601), startTime not earlier than endTime, or slidingStep smaller than period.
  • 404 Not Found: Data stream not found.
  • 422 Unprocessable Content: A Numerical function (SUM, AVG, EXTREME, MAX_VALUE, MIN_VALUE) requested against a data stream whose dataType is not double, integer, or long.

Security

  • This API requires authentication.

Request​

Responses​

Returns deviceId, dataStreamId, dataType, and data: one row per time bucket ordered by timestamp, each row carrying its timestamp plus one field per requested function that has a value for that bucket, keyed by the lowercase function name (e.g. avg, max_value).