Cognite API (v1)

Download OpenAPI specification:Download


This is the reference documentation for the Cognite API with an overview of all the available methods.


Select the Download button to download our OpenAPI specification to get started.

To import your data into Postman, select Import, and the Import modal opens. You can import items by dragging or dropping files or folders. You can choose how to import your API and manage the import settings in View Import Settings.

In the Import Settings, set the Folder organization to Tags, select Enable optional parameters to turn off the settings, and select Always inherit authentication to turn on the settings. Select Import.

Set the Authorization to Oauth2.0. By default, the settings are for Open Industrial Data. Navigate to Cognite Hub to understand how to get the credentials for use in Postman.

For more information, see Getting Started with Postman.


Most resource types can be paginated, indicated by the field nextCursor in the response. By passing the value of nextCursor as the cursor you will get the next page of limit results. Note that all parameters except cursor has to stay the same.

Parallel retrieval

As general guidance, Parallel Retrieval is a technique that should be used when due to query complexity, retrieval of data in a single request is significantly slower than it would otherwise be for a simple request. Parallel retrieval does not act as a speed multiplier on optimally running queries. By parallelizing such requests, data retrieval performance can be tuned to meet the client application needs.

CDF supports parallel retrieval through the partition parameter, which has the format m/n where n is the amount of partitions you would like to split the entire data set into. If you want to download the entire data set by splitting it into 10 partitions, do the following in parallel with m running from 1 to 10:

  • Make a request to /events with partition=m/10.
  • Paginate through the response by following the cursor as explained above. Note that the partition parameter needs to be passed to all subqueries.

Processing of parallel retrieval requests is subject to concurrency quota availability. The request returns the 429 response upon exceeding concurrency limits. See the Request throttling chapter below.

To prevent unexpected problems and to maximize read throughput, you should at most use 10 partitions. Some CDF resources will automatically enforce a maximum of 10 partitions. For more specific and detailed information, please read the partition attribute documentation for the CDF resource you're using.

Requests throttling

Cognite Data Fusion (CDF) returns the HTTP 429 (too many requests) response status code when project capacity exceeds the limit.

The throttling can happen:

  • If a user or a project sends too many (more than allocated) concurrent requests.
  • If a user or a project sends a too high (more than allocated) rate of requests in a given amount of time.

Cognite recommends using a retry strategy based on truncated exponential backoff to handle sessions with HTTP response codes 429.

Cognite recommends using a reasonable number (up to 10) of Parallel retrieval partitions.

Following these strategies lets you slow down the request frequency to maximize productivity without having to re-submit/retry failing requests.

See more here.

API versions

Version headers

This API uses calendar versioning, and version names follow the YYYYMMDD format. You can find the versions currently available by using the version selector at the top of this page.

To use a specific API version, you can pass the cdf-version: $version header along with your requests to the API.

Beta versions

The beta versions provide a preview of what the stable version will look like in the future. Beta versions contain functionality that is reasonably mature, and highly likely to become a part of the stable API.

Beta versions are indicated by a -beta suffix after the version name. For example, the beta version header for the 2023-01-01 version is then cdf-version: 20230101-beta.

Alpha versions

Alpha versions contain functionality that is new and experimental, and not guaranteed to ever become a part of the stable API. This functionality presents no guarantee of service, so its use is subject to caution.

Alpha versions are indicated by an -alpha suffix after the version name. For example, the alpha version header for the 2023-01-01 version is then cdf-version: 20230101-alpha.