Skip to main content
POST
/
timeseries
/
subscriptions
/
data
/
list
Python SDK
for batch in client.time_series.subscriptions.iterate_data("my_subscription"):
    # Changes to the subscription itself:
    print(f"Added {len(batch.subscription_changes.added)} timeseries")
    print(f"Removed {len(batch.subscription_changes.removed)} timeseries")
    print(f"Changed timeseries data in {len(batch.updates)} updates")
    # Changes to datapoints for time series in the subscription:
    for update in batch.updates:
        upserts.time_series  # The time series the update belongs to
        upserts.upserts  # The upserted datapoints, if any
        upserts.deletes  # Ranges of deleted periods, if any
    if not batch.has_next:
        break

for batch in client.time_series.subscriptions.iterate_data("my_subscription", "3d-ago"):
    pass  # do something
{
  "updates": [
    {
      "timeSeries": {
        "id": 4503599627370496,
        "isString": true,
        "type": "<string>",
        "externalId": "my.known.id",
        "instanceId": {
          "space": "<string>",
          "externalId": "<string>"
        }
      },
      "upserts": [
        {
          "timestamp": 946727999999.5,
          "value": 123,
          "status": {
            "code": 123,
            "symbol": "<string>"
          }
        }
      ],
      "deletes": [
        {
          "inclusiveBegin": 1638795554528,
          "exclusiveEnd": 1638795554528
        }
      ]
    }
  ],
  "partitions": [
    {
      "index": 123,
      "nextCursor": "<string>"
    }
  ],
  "hasNext": true,
  "subscriptionChanges": {
    "added": [
      {
        "id": 4503599627370496,
        "isString": true,
        "type": "<string>",
        "externalId": "my.known.id",
        "instanceId": {
          "space": "<string>",
          "externalId": "<string>"
        }
      }
    ],
    "removed": [
      {
        "id": 4503599627370496,
        "isString": true,
        "type": "<string>",
        "externalId": "my.known.id",
        "instanceId": {
          "space": "<string>",
          "externalId": "<string>"
        }
      }
    ]
  }
}

Authorizations

​
Authorization
string
header
required

Access token issued by the CDF project's configured identity provider. Access token must be an OpenID Connect token, and the project must be configured to accept OpenID Connect tokens. Use a header key of 'Authorization' with a value of 'Bearer $accesstoken'. The token can be obtained through any flow supported by the identity provider.

Body

application/json
​
partitions
object[]
required

Pairs of (partition, cursor) to fetch from.

​
externalId
string

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

Maximum string length: 255
Example:

"my.known.id"

​
limit
integer
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.

Required range: 1 <= x <= 100000
​
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
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.

Required range: 0 <= x <= 5
​
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.

Response

200 - application/json

A batch of data from the subscription.

Subscription data along with cursors.

​
updates
object[]
required

List of updates from the subscription, sorted by point in time they were applied to the time series. Every update contains a time series along with a set of changes to that time series.

​
partitions
object[]
required

List of partition/cursor pairs to use for the next request.

​
hasNext
boolean
required

Whether there is more data available at the time of the query. In rare cases, we may return true, even if there is no data available. If that is the case, just continue to query with the updated cursors, and it will eventually return false.

​
subscriptionChanges
object

If present, this object represents changes to the subscription definition. The subscription will now start/stop listening to changes from the time series listed here.

These changes can be triggered by explicit changes through the Update subscriptions endpoint, or they can be caused by changes in time series, in that they start/stop matching the filter for the subscription.

Time series are added to these lists when the change takes effect, which may be later than the actual trigger.

The object is partitioned - it will only be present in the response for the relevant partition, from which the time series was added/removed.

Last modified on April 23, 2026