List subscription data

Fetch the next batch of data from a given subscription and partition(s). Data can be ingested datapoints and time ranges where data is deleted. This endpoint will also return changes to the subscription itself, that is, if time series are added or removed from the subscription.

The data can be returned multiple times, there is no mechanism to acknowledge or delete data. Use cursors to paginate through the results.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
Request Body schema: application/json
externalId
string (CogniteExternalId) <= 255 characters

The external ID provided by the client. Must be unique for the resource type.

required
Array of objects (SubscriptionsDataPartitionRequestDTO)

Pairs of (partition, cursor) to fetch from.

limit
integer [ 1 .. 100000 ]
Default: 100

Approximate number of results to return across all partitions. We will batch together groups of updates, where each group come from the same ingestion request. Thus, if a single group is large, it may exceed limit, otherwise we will return up to limit results. To check whether you have reached the end, do not rely on the count. Instead, check the hasNext field.

initializeCursors
string

If partitions.cursor is not set, the default behaviour is to start from the beginning of the stream. initializeCursors can be used to override this behaviour.

The format is "N[timeunit]-ago", where timeunit is w,d,h,m (week, day, hour, minute). For instance, "2d-ago" will give a stream of changes ingested up to 2 days ago. You can also use "now" to jump straight to the end of the stream.

Note that initializeCursors is not exact; a deviation of some seconds can occur.

pollTimeoutSeconds
integer [ 0 .. 5 ]
Default: 5

The maximum time to wait for data to arrive, in seconds. As soon as data is available, the request will return immediately with the data. If the timeout is reached while waiting for data, the request will return an empty data response.

includeStatus
boolean
Default: false

Show the status code for each data point in the response. Good (code = 0) status codes are always omitted.

ignoreBadDataPoints
boolean
Default: true

Treat data points with a Bad status code as if they do not exist. Set to false to include all data points.

treatUncertainAsBad
boolean
Default: true

Treat data points with Uncertain status codes as Bad. Set to false to include uncertain data points.

Responses
200

A batch of data from the subscription.

post/timeseries/subscriptions/data/list
Request samples
application/json
{
  • "externalId": "my.known.id",
  • "partitions": [
    • {
      }
    ],
  • "limit": 100,
  • "initializeCursors": "string",
  • "pollTimeoutSeconds": 5,
  • "includeStatus": false,
  • "ignoreBadDataPoints": true,
  • "treatUncertainAsBad": true
}
Response samples
application/json
{
  • "updates": [
    • {
      }
    ],
  • "subscriptionChanges": {
    • "added": [
      ],
    • "removed": [
      ]
    },
  • "partitions": [
    • {
      }
    ],
  • "hasNext": true
}
➔ Next to List subscription members