Skip to main content
POST
/
streams
/
{streamId}
/
records
/
sync
Sync records from a stream
curl --request POST \
  --url https://{cluster}.cognitedata.com/api/v1/projects/{project}/streams/{streamId}/records/sync \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sources": [
    {
      "source": {
        "type": "container,",
        "space": "mySpace,",
        "externalId": "myContainer"
      },
      "properties": [
        "someProperty"
      ]
    }
  ],
  "filter": {
    "and": [
      {
        "containsAll": {
          "property": [
            "mySpace",
            "myContainer",
            "myProperty"
          ],
          "values": [
            10011,
            10012
          ]
        }
      },
      {
        "range": {
          "property": [
            "my_space",
            "my_container",
            "my_weight"
          ],
          "gte": 0
        }
      }
    ]
  },
  "cursor": "c29tZSBjdXJzb3I=",
  "initializeCursor": "42d-ago",
  "limit": 42
}
'
{
  "items": [
    {
      "space": "mySpace",
      "externalId": "some_id",
      "createdTime": 1720616232,
      "lastUpdatedTime": 1720616232,
      "status": "created",
      "properties": {}
    }
  ],
  "nextCursor": "c29tZSBjdXJzb3I=",
  "hasNext": true
}

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

Change filter specification.

​
sources
propertiesForContainer · object[]

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

Required array length: 1 - 10 elements
​
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
      }
    }
  ]
}
​
cursor
string

A cursor returned from the previous sync request.

Required string length: 1 - 100000
Example:

"c29tZSBjdXJzb3I="

​
initializeCursor
string

The format is "duration-ago", where duration is a correct duration representation: 3m, 400h, 25d, etc. For instance, "2d-ago" will give a stream of changes ingested up to 2 days ago.

If cursor is not set, initializeCursor is used to choose a shift where to start the stream reading. If initializeCursor is not set, the cursor is required. If the cursor is provided, initializeCursor is ignored.

Note that initializeCursor is not exact; a deviation up to few seconds can occur.

Required string length: 6 - 100
Example:

"42d-ago"

​
limit
integer
default:10

Limits the number of results to return.

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

42

Response

The next chunk of matching the filter records starting from the cursor in the request.

Note: The maximum total response size is 10MB.

​
items
syncRecordItem · object[]
required

List of records.

​
nextCursor
string
required

A cursor to use in the next request as a starting point to get the next chunk of records.

Example:

"c29tZSBjdXJzb3I="

​
hasNext
boolean
required

The attribute indicates if there are more records to read in the storage or the cursor points to the last item.

Example:

true

Last modified on April 23, 2026