Cognite OData services - Cognite Docs

Open Data Protocol (OData) is an open standard defining best practices for building and consuming RESTful APIs. OData offers:

Standardized query syntax: Enables consistent filtering, sorting, pagination, and projections across different data sources.
Metadata support: Clients can discover the data structure and types via metadata documents.
Interoperability: Any client that supports HTTP and understands OData can consume OData services.

Cognite provides an asset-centric OData service and a data-modeling OData service. Both services wrap the standard Cognite APIs, implementing an OData Version 4 API for read-only purposes. They translate OData requests into corresponding Cognite API calls, allowing you to interact with CDF data using OData-compatible clients and tools.

Assets, events, sequences, and asset-centric file and time series metadata in the asset-centric OData service are deprecated. Use the data modeling OData service for data modeling resources. See Deprecated and retired features.

Using the OData services

To interact with the Cognite OData services, you make HTTP GET requests to specific endpoints.

Authenticate

To authenticate with the OData services, you must include a bearer token in the authorization header of your HTTP requests. For example:

Authorization: Bearer {YourAccessToken}

You can obtain an access token using the appropriate authentication flow for your setup (e.g., OAuth 2.0, OpenID Connect). For more details, refer to the Authentication documentation.

Make requests

To retrieve all assets in a project:

GET https://{cluster}.cognitedata.com/odata/{apiVersion}/projects/{project}/Assets

Where:

{cluster}: The CDF cluster name (e.g., westeurope-1).
{apiVersion}: The OData service API version (e.g., v1).
{project}: Your CDF project name.

Use query parameters to filter, sort, select, and paginate data.

Filtering - use the $filter query parameter to filter data. Example: Retrieve assets where Name equals 'Pump 1': GET .../Assets?$filter=Name eq 'Pump 1'
Selecting fields- use the $select query parameter to retrieve specific fields. Example: Retrieve only the Id and Name of assets: GET .../Assets?$select=Id,Name
Sorting - use the $orderby query parameter to sort results. Example: Order assets by Name ascending: GET .../Assets?$orderby=Name asc
Expanding related entities - use the $expand query parameter to include related entities. Example: Retrieve an asset along with its parent: GET .../Assets(702630644612)/Parent?$expand=Parent Note: Not all entities and relationships support expansion. Refer to the individual service documentation for details.
Combining query parameters - you can combine multiple query parameters to refine your request. Example: Retrieve the Id and Name of assets where Name starts with 'Pump', ordered by Name, and retrieve the first 10 results: GET .../Assets?$filter=startswith(Name,'Pump')&$select=Id,Name&$orderby=Name asc&$top=10

The OData services return responses in JSON format, following the OData V4 standard. Example response:

{
  "@odata.context": "https://{cluster}.cognitedata.com/odata/{apiVersion}/projects/{project}/$metadata#Assets/",
  "value": [
    {
      "Id": "12345",
      "DataSetId": null,
      "ExternalId": "WMT:VAL",
      "Name": "Pump 1",
      "Description": "Main pump"
      // other properties
    }
  ]
}

The OData service may paginate the response for large result sets. The response includes a @odata.nextLink property with a URL to retrieve the next page of results. Example:

{
  "@odata.context": "https://{cluster}.cognitedata.com/odata/{apiVersion}/projects/{project}/$metadata#Assets",
  "value": [ // records ],
  "@odata.nextLink": "https://{cluster}.cognitedata.com/odata/{apiVersion}/projects/{project}/Assets?$skipToken=123"
}

Limitations and supported features

The OData services aim to conform to the OData V4 standard, but some features may be limited or unsupported due to underlying constraints of the Cognite APIs. Refer to the individual service documentation for detailed information on supported features and limitations.

​Using the OData services

​Authenticate

​Make requests

​Limitations and supported features

Using the OData services

Authenticate

Make requests

Limitations and supported features