Retrieve data points

Retrieves a list of data points from multiple time series in a project. This operation supports aggregation and pagination. Learn more about aggregation.

Note: when start isn't specified in the top level and for an individual item, it will default to epoch 0, which is 1 January, 1970, thus excluding potential existent data points before 1970. start needs to be specified as a negative number to get data points before 1970.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
Request Body schema: application/json
required

Specify parameters to query for multiple data points. If you omit fields in individual data point query items, the top-level field values are used. For example, you can specify a default limit for all items by setting the top-level limit field. If you request aggregates, only the aggregates are returned. If you don't request any aggregates, all data points are returned.

required
Array of QueryWithInternalId (object) or QueryWithExternalId (object) (DatapointsQuery) [ 1 .. 100 ] items
integer or string (TimestampOrStringStart)

Get datapoints starting from, and including, this time. The format is N[timeunit]-ago where timeunit is w,d,h,m,s. Example: '2d-ago' gets datapoints that are up to 2 days old. You can also specify time in milliseconds since epoch. Note that for aggregates, the start time is rounded down to a whole granularity unit (in UTC timezone). Daily granularities (d) are rounded to 0:00 AM; hourly granularities (h) to the start of the hour, etc.

integer or string (TimestampOrStringEnd)

Get datapoints up to, but excluding, this point in time. Same format as for start. Note that when using aggregates, the end will be rounded up such that the last aggregate represents a full aggregation interval containing the original end, where the interval is the granularity unit times the granularity multiplier. For granularity 2d, the aggregation interval is 2 days, if end was originally 3 days after the start, it will be rounded to 4 days after the start.

limit
integer <int32>
Default: 100

Returns up to this number of data points. The maximum is 100000 non-aggregated data points and 10000 aggregated data points in total across all queries in a single request.

aggregates
Array of strings (Aggregate) [ 1 .. 10 ] items unique

Specify the aggregates to return. Omit to return data points without aggregation.

Items Enum: "average" "max" "min" "count" "sum" "interpolation" "stepInterpolation" "totalVariation" "continuousVariance" "discreteVariance"
granularity
string

The time granularity size and unit to aggregate over. Valid entries are 'day, hour, minute, second', or short forms 'd, h, m, s', or a multiple of these indicated by a number as a prefix. For 'second' and 'minute', the multiple must be an integer between 1 and 120 inclusive; for 'hour' and 'day', the multiple must be an integer between 1 and 100000 inclusive. For example, a granularity '5m' means that aggregates are calculated over 5 minutes. This field is required if aggregates are specified.

includeOutsidePoints
boolean
Default: false

Defines whether to include the last data point before the requested time period and the first one after. This option can be useful for interpolating data. It's not available for aggregates or cursors. Note: If there are more than limit data points in the time period, we will omit the excess data points and then append the first data point after the time period, thus causing a gap with omitted data points. When this is the case, we return up to limit+2 data points. When doing manual paging (sequentially requesting smaller intervals instead of requesting a larger interval and using cursors to get all the data points) with this field set to true, the start of the each subsequent request should be one millisecond more than the timestamp of the second-to-last data point from the previous response. This is because the last data point in most cases will be the extra point from outside the interval.

ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses
200

Lists of data points for the specified queries.

400

IDs not found.

post/timeseries/data/list
Request samples
application/json
{
  • "items": [
    • {
      }
    ],
  • "start": 0,
  • "end": 0,
  • "limit": 100,
  • "aggregates": [
    • "average"
    ],
  • "granularity": "1h",
  • "includeOutsidePoints": false,
  • "ignoreUnknownIds": false
}
Response samples
{
  • "items": [
    • {
      }
    ]
}