Python SDK

from cognite.client.data_classes.filters import Equals
is_numeric = Equals("is_string", False)
res = client.time_series.filter(filter=is_numeric, sort="external_id")

from cognite.client.data_classes.filters import Equals
from cognite.client.data_classes.time_series import TimeSeriesProperty, SortableTimeSeriesProperty
is_numeric = Equals(TimeSeriesProperty.is_string, False)
res = client.time_series.filter(filter=is_numeric, sort=SortableTimeSeriesProperty.external_id)
res = client.time_series.list(limit=5)

for ts in client.time_series:
    ts # do something with the time series

for ts_list in client.time_series(chunk_size=2500):
    ts_list # do something with the time series

from cognite.client.data_classes import filters
in_timezone = filters.Prefix(["metadata", "timezone"], "Europe")
res = client.time_series.list(advanced_filter=in_timezone, sort=("external_id", "asc"))

from cognite.client.data_classes import filters
from cognite.client.data_classes.time_series import TimeSeriesProperty, SortableTimeSeriesProperty
in_timezone = filters.Prefix(TimeSeriesProperty.metadata_key("timezone"), "Europe")
res = client.time_series.list(
    advanced_filter=in_timezone,
    sort=(SortableTimeSeriesProperty.external_id, "asc"))

from cognite.client.data_classes import filters
not_instrument_lvl5 = filters.And(
   filters.ContainsAny("labels", ["Level5"]),
   filters.Not(filters.ContainsAny("labels", ["Instrument"]))
)
res = client.time_series.list(asset_subtree_ids=[123456], advanced_filter=not_instrument_lvl5)

{
  "items": [
    {
      "id": 4503599627370496,
      "isString": true,
      "type": "<string>",
      "isStep": true,
      "createdTime": 1730204346000,
      "lastUpdatedTime": 1730204346000,
      "externalId": "<string>",
      "instanceId": {
        "space": "<string>",
        "externalId": "<string>"
      },
      "name": "<string>",
      "metadata": {},
      "unit": "<string>",
      "unitExternalId": "<string>",
      "assetId": 4503599627370496,
      "description": "<string>",
      "securityCategories": [
        123
      ],
      "dataSetId": 4503599627370496
    }
  ],
  "nextCursor": "<string>"
}

Filter time series

Required capabilities: timeSeriesAcl:READ

Retrieves a list of time series that match the given criteria.

Advanced filtering

The advancedFilter 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 filter	Supported fields	Description and example
`containsAll`	Array type fields	Only includes results which contain all of the specified values. `{"containsAll": {"property": ["property"], "values": [1, 2, 3]}}`
`containsAny`	Array type fields	Only includes results which contain at least one of the specified values. `{"containsAny": {"property": ["property"], "values": [1, 2, 3]}}`
`equals`	Non-array type fields	Only includes results that are equal to the specified value. `{"equals": {"property": ["property"], "value": "example"}}`
`exists`	All fields	Only includes results where the specified property exists (has a value). `{"exists": {"property": ["property"]}}`
`in`	Non-array type fields	Only includes results that are equal to one of the specified values. `{"in": {"property": ["property"], "values": [1, 2, 3]}}`
`prefix`	String type fields	Only includes results which start with the specified text. `{"prefix": {"property": ["property"], "value": "example"}}`
`range`	Non-array type fields	Only includes results that fall within the specified range. `{"range": {"property": ["property"], "gt": 1, "lte": 5}}` Supported operators: `gt`, `lt`, `gte`, `lte`
`search`	`["name"]` and `["description"]`	Introduced to provide functional parity with the /timeseries/search endpoint. `{"search": {"property": ["property"], "value": "example"}}`

Supported properties

Property	Type
`["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
`["securityCategories"]`	array of numbers

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).
search filter value must not be blank, and the length must be in the range [1, 128], and there may be at most two search filters in the entire filter query.
The maximum length of the value of a leaf filter that is applied to a string property is 256.

Sorting

By default, time series are sorted by their creation time in ascending order. Sorting by another property or by several other properties can be explicitly requested via the sort field, which must contain a list of one or more sort specifications. Each sort specification indicates the property to sort on and, optionally, the order in which to sort (defaults to asc). If multiple sort specifications are supplied, the results are sorted on the first property, and those with the same value for the first property are sorted on the second property, and so on.
Partitioning is done independently of sorting; there is no guarantee of sort order between elements from different partitions.

Null values

In case the nulls field has the auto value, or the field isn’t specified, null (missing) values are considered bigger than any other values. They are placed last when sorting in the asc order and first in the desc order. Otherwise, missing values are placed according to the nulls field (last or first), and their placement won’t depend on the order field. Note that the number zero, empty strings, and empty lists are all considered not null.

Example

{
  "sort": [
    {
      "property" : ["createdTime"],
      "order": "desc",
      "nulls": "last"
    },
    {
      "property" : ["metadata", "<someCustomKey>"]
    }
  ]
}

Properties

You can sort on the following properties:

Property
`["assetId"]`
`["createdTime"]`
`["dataSetId"]`
`["description"]`
`["externalId"]`
`["lastUpdatedTime"]`
`["metadata", "<someCustomKey>"]`
`["name"]`
`["instanceId", "space"]`
`["instanceId", "externalId"]`

Limits

The sort array must contain 1 to 2 elements.

POST

timeseries

list

Python SDK

from cognite.client.data_classes.filters import Equals
is_numeric = Equals("is_string", False)
res = client.time_series.filter(filter=is_numeric, sort="external_id")

from cognite.client.data_classes.filters import Equals
from cognite.client.data_classes.time_series import TimeSeriesProperty, SortableTimeSeriesProperty
is_numeric = Equals(TimeSeriesProperty.is_string, False)
res = client.time_series.filter(filter=is_numeric, sort=SortableTimeSeriesProperty.external_id)
res = client.time_series.list(limit=5)

for ts in client.time_series:
    ts # do something with the time series

for ts_list in client.time_series(chunk_size=2500):
    ts_list # do something with the time series

from cognite.client.data_classes import filters
in_timezone = filters.Prefix(["metadata", "timezone"], "Europe")
res = client.time_series.list(advanced_filter=in_timezone, sort=("external_id", "asc"))

from cognite.client.data_classes import filters
from cognite.client.data_classes.time_series import TimeSeriesProperty, SortableTimeSeriesProperty
in_timezone = filters.Prefix(TimeSeriesProperty.metadata_key("timezone"), "Europe")
res = client.time_series.list(
    advanced_filter=in_timezone,
    sort=(SortableTimeSeriesProperty.external_id, "asc"))

from cognite.client.data_classes import filters
not_instrument_lvl5 = filters.And(
   filters.ContainsAny("labels", ["Level5"]),
   filters.Not(filters.ContainsAny("labels", ["Instrument"]))
)
res = client.time_series.list(asset_subtree_ids=[123456], advanced_filter=not_instrument_lvl5)

{
  "items": [
    {
      "id": 4503599627370496,
      "isString": true,
      "type": "<string>",
      "isStep": true,
      "createdTime": 1730204346000,
      "lastUpdatedTime": 1730204346000,
      "externalId": "<string>",
      "instanceId": {
        "space": "<string>",
        "externalId": "<string>"
      },
      "name": "<string>",
      "metadata": {},
      "unit": "<string>",
      "unitExternalId": "<string>",
      "assetId": 4503599627370496,
      "description": "<string>",
      "securityCategories": [
        123
      ],
      "dataSetId": 4503599627370496
    }
  ],
  "nextCursor": "<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

Filter request for time series. Filters exact field matching or timestamp ranges inclusive min and max.

filter

object

Show child attributes

advancedFilter

and · object

A query that matches items matching boolean combinations of other queries. It is built by nesting one or more Boolean clauses, each of which is one of and, or, and not. Each such clause contains one or more child clauses (though not can only have one). Each child clause can be either another Boolean clause or a leaf filter.

Show child attributes

Example:

{
  "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"
          }
        }
      ]
    }
  ]
}

limit

integer<int32>

default:100

Return up to this many results.

Required range: 1 <= x <= 1000

cursor

string

Example:

"4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo"

partition

string

Splits the data set into N partitions. The attribute is specified as a "M/N" string, where M is a natural number in the interval of [1, N]. You need to follow the cursors within each partition in order to receive all the data.

To prevent unexpected problems and maximize read throughput, you should at most use 10 (N <= 10) partitions.

When using more than 10 partitions, CDF may reduce the number of partitions silently. For example, CDF may reduce the number of partitions to K = 10 so if you specify an X/N partition value where X = 8 and N = 20 - i.e. "partition": "8/20"- then CDF will change N to N = K = 10 and process the request. But if you specify the X/N partition value where X = 11 (X > K) and N = 20 - i.e. "partition": "11/20"- then CDF will reply with an empty result list and no cursor in the response.\

In future releases of the resource APIs, Cognite may reject requests if you specify more than 10 partitions. When Cognite enforces this behavior, the requests will result in a 400 Bad Request status.

Example:

"1/10"

sort

object[]

Sort by array of selected properties.

Required array length: 1 - 2 elements

Show child attributes

Response

200 - application/json

Response with a list of time series matching the specified criteria.

A list of objects and possible cursors to get the next results page.

items

object[]

required

Show child attributes

nextCursor

string

The cursor to get the next page of results (if available).

Last modified on June 2, 2026

Delete time series

List time series

⌘I

Documentation Index

Authorizations

Body

Response