Skip to main content
POST
/
streams
/
{streamId}
/
records
/
filter
Retrieve records from a stream
curl --request POST \
  --url https://{cluster}.cognitedata.com/api/v1/projects/{project}/streams/{streamId}/records/filter \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "lastUpdatedTime": {
    "gt": 1705341600000,
    "lt": "2030-05-15T18:00:00.00Z"
  },
  "filter": {
    "and": [
      {
        "containsAll": {
          "property": [
            "mySpace",
            "myContainer",
            "myProperty"
          ],
          "values": [
            10011,
            10012
          ]
        }
      },
      {
        "range": {
          "property": [
            "my_space",
            "my_container",
            "my_weight"
          ],
          "gte": 0
        }
      }
    ]
  },
  "sources": [
    {
      "source": {
        "type": "container,",
        "space": "mySpace,",
        "externalId": "myContainer"
      },
      "properties": [
        "someProperty"
      ]
    }
  ],
  "limit": 42,
  "sort": [
    {
      "property": [
        "space"
      ],
      "direction": "descending"
    }
  ]
}
'
{
  "items": [
    {
      "space": "mySpace",
      "externalId": "some_id",
      "createdTime": 1720616232,
      "lastUpdatedTime": 1720616232,
      "properties": {}
    }
  ]
}

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.

Path Parameters

​
streamId
string
required

An identifier of the stream where the records are stored.

Required string length: 1 - 100
Pattern: ^[a-z]([a-z0-9_-]{0,98}[a-z0-9])?$
Example:

"test1"

Body

application/json

Filter records based on the last updated time, on the space and on container(s) properties. The response supports custom sorting. Otherwise, the records in the response are sorted by last updated time.

Defines a filter request. This will let you fetch records with some necessary properties filtered by different criteria.

​
lastUpdatedTime
lastUpdatedTime · object

Matches records with the last updated time within the provided range. This attribute is mandatory for immutable streams but it's optional for mutable streams. The maximum time interval that can be defined by the attribute is limited by the stream settings. If more data needs to be queried than allowed by the stream settings, it should be done with multiple requests. For example, if stream allows querying up to 1 month of data, but a quarterly report is needed, the solution is to make 3 requests, one for each month, and then aggregate the responses.

The range must include at least a left (gt or gte) bound. It is not allowed to specify two upper or lower bounds, e.g. gte and gt, in the same filter.

gte: Greater than or equal to. gt: Greater than. lte: Less than or equal to. lt: Less than.

Note: lastUpdatedTime is a CDF generated timestamp that marks the moment a record is stored in the API

The range bounds can be specified in two formats:

  • String: An ISO-8601 formatted date-time string (e.g., 2030-05-15T18:00:00.00Z).
  • Integer: The number of milliseconds since the Unix epoch (e.g., 1705341600000).
Example:
{
  "gt": 1705341600000,
  "lt": "2030-05-15T18:00:00.00Z"
}
​
filter
and · object

Build a new query by combining other queries, using boolean operators. We support the and, or, and not boolean operators.

Example:
{
  "and": [
    {
      "containsAll": {
        "property": ["mySpace", "myContainer", "myProperty"],
        "values": [10011, 10012]
      }
    },
    {
      "range": {
        "property": ["my_space", "my_container", "my_weight"],
        "gte": 0
      }
    }
  ]
}
​
sources
propertiesForContainer · object[]

List of containers and their properties which values should be selected for the response.

Required array length: 1 - 10 elements
​
limit
integer
default:10

Limits the number of results to return.

Required range: 1 <= x <= 1000
Example:

42

​
sort
sortSpecification · object[]

Ordered list of sorting specifications (property, direction, etc) to sort on.

Required array length: 1 - 5 elements

Response

List of matching records.

Note: The maximum total response size is 20MB.

​
items
recordItem · object[]
required

List of records.

Last modified on April 23, 2026