Skip to main content
POST
/
timeseries
/
subscriptions
Python SDK
from cognite.client.data_classes import DataPointSubscriptionWrite
sub = DataPointSubscriptionWrite(
    external_id="my_subscription",
    name="My subscription",
    partition_count=1,
    time_series_ids=["myFistTimeSeries", "mySecondTimeSeries"])
created = client.time_series.subscriptions.create(sub)

from cognite.client.data_classes import DataPointSubscriptionWrite
from cognite.client.data_classes.data_modeling import NodeId
sub = DataPointSubscriptionWrite(
    external_id="my_subscription",
    name="My subscription with Data Model Ids",
    partition_count=1,
    instance_ids=[NodeId("my_space", "myFistTimeSeries"), NodeId("my_space", "mySecondTimeSeries")])
created = client.time_series.subscriptions.create(sub)

from cognite.client.data_classes import DataPointSubscriptionWrite
from cognite.client.data_classes import filters as flt
from cognite.client.data_classes.datapoints_subscriptions import DatapointSubscriptionProperty
is_numeric_stepwise = flt.And(
    flt.Equals(DatapointSubscriptionProperty.is_string, False),
    flt.Equals(DatapointSubscriptionProperty.is_step, True))
sub = DataPointSubscriptionWrite(
    external_id="my_subscription",
    name="My subscription for numeric, stepwise time series",
    partition_count=1,
    filter=is_numeric_stepwise)
created = client.time_series.subscriptions.create(sub)
{
  "items": [
    {
      "externalId": "my.known.id",
      "partitionCount": 50,
      "createdTime": 1730204346000,
      "lastUpdatedTime": 1730204346000,
      "name": "<string>",
      "description": "<string>",
      "dataSetId": 4503599627370496,
      "timeSeriesCount": 123,
      "filter": {
        "or": [
          {
            "not": {
              "and": [
                {
                  "equals": {
                    "property": [
                      "metadata",
                      "manufacturer"
                    ],
                    "value": "acme"
                  }
                },
                {
                  "in": {
                    "property": [
                      "name"
                    ],
                    "values": [
                      "pump-1-temperature",
                      "motor-9-temperature"
                    ]
                  }
                },
                {
                  "range": {
                    "property": [
                      "dataSetId"
                    ],
                    "gte": 1,
                    "lt": 10
                  }
                }
              ]
            }
          },
          {
            "and": [
              {
                "equals": {
                  "property": [
                    "assetId"
                  ],
                  "value": 1234
                }
              },
              {
                "equals": {
                  "property": [
                    "description"
                  ],
                  "value": "Temperature in Celsius"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

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

The subscriptions to create.

items
object[]
required
Subscription definitions. A subscription may be configured explicitly with a list of time series, or it may be a configured dynamically through a filter. The subscription cannot change type later.

An explicit list must be manually updated by the user, while a filter will be updated automatically whenever a time series is added/deleted/updated (eventually consistent).

The filter subscriptions uses the same syntax as advanced filters in the Filter time series endpoint, with two exceptions: The field is named `filter` instead of `advancedFilter`, and we do not support the `search` LeafFilter.

Advanced filtering

The filter field lets you create complex filtering expressions that combine simple operations, such as equals, prefix, and exists, by using the Boolean operators and, or, and not. Filtering applies to basic fields as well as metadata. See the advancedFilter syntax in the request example.

Supported leaf filters

Leaf filterSupported fieldsDescription and example
containsAllArray type fieldsOnly includes results which contain all of the specified values.
{"containsAll": {"property": ["property"], "values": [1, 2, 3]}}
containsAnyArray type fieldsOnly includes results which contain at least one of the specified values.
{"containsAny": {"property": ["property"], "values": [1, 2, 3]}}
equalsNon-array type fieldsOnly includes results that are equal to the specified value.
{"equals": {"property": ["property"], "value": "example"}}
existsAll fieldsOnly includes results where the specified property exists (has a value).
{"exists": {"property": ["property"]}}
inNon-array type fieldsOnly includes results that are equal to one of the specified values.
{"in": {"property": ["property"], "values": [1, 2, 3]}}
prefixString type fieldsOnly includes results which start with the specified text.
{"prefix": {"property": ["property"], "value": "example"}}
rangeNon-array type fieldsOnly includes results that fall within the specified range.
{"range": {"property": ["property"], "gt": 1, "lte": 5}}
Supported operators: gt, lt, gte, lte

Supported properties

PropertyType
["description"]string
["externalId"]string
["metadata", "<someCustomKey>"]string
["name"]string
["unit"]string
["unitExternalId"]string
["unitQuantity"]string
["instanceId", "space"]string
["instanceId", "externalId"]string
["assetId"]number
["assetRootId"]number
["createdTime"]number
["dataSetId"]number
["id"]number
["lastUpdatedTime"]number
["isStep"]Boolean
["isString"]Boolean
["type"]string

Limits

  • Filter query max depth: 10.
  • Filter query max number of clauses: 100.
  • and and or clauses must have at least one element (and at most 99, since each element counts towards the total clause limit, and so does the and/or clause itself).
  • The property array of each leaf filter has the following limitations:
    • Number of elements in the array is 1 or 2.
    • Elements must not be null or blank.
    • Each element max length is 256 characters.
    • The property array must match one of the existing properties (static top-level property or dynamic metadata property).
  • containsAll, containsAny, and in filter values array size must be in the range [1, 100].
  • containsAll, containsAny, and in filter values array must contain elements of number or string type (matching the type of the given property).
  • range filter must have at lest one of gt, gte, lt, lte attributes. But gt is mutually exclusive to gte, while lt is mutually exclusive to lte.
  • gt, gte, lt, lte in the range filter must be of number or string type (matching the type of the given property).
  • The maximum length of the value of a leaf filter that is applied to a string property is 256.
Required array length: 1 element

Response

201 - application/json

A list of subscriptions that were created.

List of subscriptions.

items
object[]
required
Last modified on April 23, 2026