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) or QueryWithInstanceId (object) (DatapointsQuery) [ 1 .. 100 ] items
integer or string (TimestampOrStringStart)
integer or string (TimestampOrStringEnd)
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) non-empty 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" "countGood" "countUncertain" "countBad" "durationGood" "durationUncertain" "durationBad"
granularity
string

The time granularity size and unit to aggregate over. Valid entries are 'month, day, hour, minute, second', or short forms 'mo, 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', 'day', and 'month', 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.

timeZone
string
Default: "UTC"

For aggregates of granularity 'hour' and longer, which time zone should we align to. Align to the start of the hour, start of the day or start of the month. For time zones of type Region/Location, the aggregate duration can vary, typically due to daylight saving time. For time zones of type UTC+/-HH:MM, use increments of 15 minutes.

Note: Time zones with minute offsets (e.g. UTC+05:30 or Asia/Kolkata) may take longer to execute. Historical time zones, with offsets not multiples of 15 minutes, are not supported.

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,
  • "timeZone": "Europe/Oslo or UTC+05:30",
  • "ignoreUnknownIds": false
}
Response samples
{
  • "items": [
    • {
      }
    ]
}
➔ Next to Retrieve latest data point