Cognite API (v1)

Download OpenAPI specification:Download

Introduction

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

Postman

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.

Pagination

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

If you want to download a lot of resources (let's say events), paginating through millions of records can be slow. We support 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 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.

Changelog

This article documents all notable changes to the Cognite Data Fusion (CDF) API v1.

2023-10-23

Files

Added

  • Added multipart upload endpoints for the files API. This enables upload of files larger than 5 GiB, in a uniform way for all CDF cloud environments. Optionally use parallel part upload, for greater upload speed. See the documentation for the new endpoints at:

2023-10-10

Entity matching

Added

  • Entity matching pipelines are now in v1. We resuscitated the old playground API and made some changes. We will keep the new v1 API in beta for the foreseeable future.

Vision (Contextualization)

Added

  • New computer vision models (beta) are available in Vision extract service, including digital, dial and level gauge readers, valve state detection (open/closed) and model to segment objects in images.

2023-10-05

Hosted extractors

Added

  • Hosted extractors API (Beta)
    • Use the new Hosted extractors feature to create simple streaming extractors running inside CDF, streaming data from sources available on the internet directly into CDF. Currently supports Azure Event Hub and MQTT. Support is planned for Kafka and REST APIs.

2023-09-27

3D

Changed

  • If the 3d model processing is ongoing or has failed, the 3d api nodes endpoints will now return error code 400 with the response body "Revision processing is not yet complete" or "Revision processing failed" respectively. The previous behavior was to return an empty or partial items list in these cases. Before calling any 3d api nodes endpoints, clients should check that the model revision has "status":"Done".

2023-08-25

Transformations

Changed

  • Fixed wrong description for fields in "transformations/update" and "/transformations/schedules/update"

2023-08-22

2023-08-22

Functions

Changed

  • Remove Functions runtime "py37".

2023-08-22

Time series

Added

  • Data point subscriptions (Beta)
    • Use the new Data point subscriptions feature to configure a subscription to listen to changes in one or more time series (in ingestion order). The feature is intended to be used where data points consumers need to keep up to date with changes to one or more time series without the need to read the entire time series again. (Beta)

2023-08-10

Time series

Added

  • Advanced query language support reaches General Availability (GA).

Sequences

Added

  • Advanced query language support reaches General Availability (GA).

2023-08-08

Assets

Added

  • Advanced query language support reaches General Availability (GA).
    • Advanced search, filtering, and sorting capabilities in the Filter assets endpoint.
    • Advanced aggregation capabilities in the Aggregate assets endpoint.

Events

Added

  • Advanced query language support reaches General Availability (GA).
    • Advanced search, filtering, and sorting capabilities in the Filter events endpoint.
    • Advanced aggregation capabilities in the Aggregate events endpoint.

Documents

Added

  • Advanced query language support reaches General Availability (GA).

2023-06-27

IAM (Identity and access management)

Changed

  • Identity providers (IdP) are required to be compatible with the OpenID Connect Discovery 1.0 standard, and compliance will now be enforced by the Projects API.

    • The oidcConfiguration.jwksUrl and oidcConfiguration.tokenUrl can be entirely omitted when updating the OIDC configuration for a project.
    • The oidcConfiguration.jwksUrl and oidcConfiguration.tokenUrl are preserved for backwards compatibility of the API. However, if these are specified as part of the request body, the value must match excatly the values that are specified in the OpenID provider configuration document for the configured issuer (can be found at https://{issuer-url}/.well-known/openid-configuration). If the values does not match, the API will return an error message.
  • The oidcConfiguration.skewMs has been deprecated but remains part of the API for backwards compatibility. It can be omitted from the request. If included, it must always be set to 0.

  • The oidcConfiguration.isGroupCallbackEnabled has been deprecated but remains part of the API for backwards compatibility. It can be omitted from the request.

    • For projects configured to use Azure Active Directory as the identity provider, if this value is specified in the request, it must always be set to true.

2023-06-05

Data Modeling

Added

  • Added support for an autoCreateDirectRelations option on the endpoint for ingesting instances. This option lets the user specify whether to create missing target nodes of direct relations.

Removed

  • Removed support for the deprecated per-item sources field on the /instances/byids endpoint.

Time series

Added

  • Added advanced query language support (Beta).

Sequences

Added

  • Added advanced query language support (Beta).

2023-05-19

Transformations

Added

  • Adding support for data model centric and view centric schema.

2023-04-24

Transformations

Removed

  • Removing support for authentication via API keys when creating or updating transformations.

2023-05-04

Annotations

Added

  • Added image.InstanceLink and diagrams.InstanceLink annotation types to allow you to link from objects discovered in images and engineering diagrams to data model instances.

2023-04-18

All resources

Added

Changed

  • Updated the Parallel retrieval documentation.
  • Aligned endpoint naming within Assets, Data sets, Events, and Files.

Assets

Added

  • Added advanced query language support (Beta).
    • Advanced search, filtering, and sorting capabilities in the Filter assets endpoint.
    • Advanced aggregation capabilities in the Aggregate assets endpoint.

Events

Added

  • Added advanced query language support (Beta).
    • Advanced search, filtering, and sorting capabilities in the Filter events endpoint.
    • Advanced aggregation capabilities in the Aggregate events endpoint.

Documents

Added

  • Added advanced query language support (Beta).

2023-04-12

Sessions

Fixed

  • Fixed the API documentation for the request body of the POST /projects/{project}/sessions/byids endpoint. The documentation incorrectly stated the request body schema as specifying the list of session IDs to retrieve, in the form {"items": [42]} - it should in fact be {"items": [{"id": 42}]}. The documentation has been updated to reflect this.

  • Fixed the API documentation for the response body of the POST /projects/{project}/sessions/byids endpoint. The documentation incorrectly stated nextCursor and previousCursor fields as being returned from the response, which was not the case, and these fields have now been removed from the API documentation.

2023-04-04

Transformations

Change

  • Transformations support new target types for view-centric data model instances.

Added

  • Added target types nodes and edges.

2023-03-06

Documents

Change

  • Renamed "approximateCardinality" aggregate to "cardinalityValues" to unify the search spec in Cognite.
  • "uniqueProperties" aggregate no longer supports pagination. It returns unique properties (up to 10000) in the specified path. The results are sorted by frequency.

Added

  • Added "allUniqueProperties" aggregate that returns all unique properties. The response contains a cursor that can be used to fetch all pages of data.

2023-02-03

Seismic

Added

  • Batch downloading of seismics as a ZIP archive is now an experimental v1 endpoint. A user requires the experimental ACL to use this endpoint, and any other ACLs and scopes to read the downloadable seismics.

Fixed

  • The documentation for downloading seismics as SEG-Y files is part of v1. The API documentation didn't reflect that the endpoint had been promoted to version 1.

2023-02-07

Documents

Added

  • Added highlight field in the search endpoint to indicate whether matches in search results should be highlighted.

2023-01-18

3D

Added

  • Added support for using names filter in list nodes endpoint.

2023-01-17

Authentication

Removed

We've removed authentication via CDF service accounts and API keys, and user sign-in via /login.

3D

Added

  • Added support for storing translation and scale for model revision.

2023-01-12

Documents

Added

  • Added support for approximateCardinality aggregate.

2023-01-10

Documents

Added

  • Added the search leaf filter, to allow filtering by searching through specified properties.

2023-01-09

Documents

Added

  • Added the uniqueProperties aggregation, which can be used to find all the metadata keys in use.

2023-01-06

Documents

Added

  • Added inAssetSubtree filter to filter documents that have a related asset in a subtree rooted at any of the specified IDs.

2023-01-02

Documents

Added

  • Added advanced filters for metadata (prefix, in, equals)

2022-12-06

3D

Added

  • Added get3DNodesById endpoint to be able to fetch 3D nodes mapped to an asset.

2022-12-16

Time series

Changed

  • Timestamps of data points may now be as large as 4102444799999 (23:59:59.999, December 31, 2099). The previous limit was the year 2050.

2022-11-29

Events

Added

  • Added nulls field to the sort property specification

2022-11-17

Time series

Added

2022-10-14

Geospatial

Added

2022-10-11

Transformations

Added

  • Added capability to run a transformation with Nonce credentials provided through the Run endpoint.

2022-10-06

IAM (Identity and access management)

Added

2022-09-09

Vision (Contextualization)

Added

  • Move Vision extract service from playground to V1.

2022-08-12

Time series

Changed

2022-07-21

Transformations

Added

  • Added authentication using nonce for transformation's exisiting endpoints.

2022-06-21

Annotations (Data organization)

Added

  • Moved the annotation service from playground to v1.

2022-07-07

Events

Removed

2022-06-13

IAM (Identity and access management)

Added

2022-05-20

Documents

Added

  • Added the POST /documents/aggregate endpoint. The endpoint allows you to count documents optionally grouped by a property and also to retrieve all unique values of a property.

2022-05-12

Documents

Added

  • Added the POST /documents/list endpoint. The endpoint allows you to iterate through all the documents in a project.
  • Added the POST /documents/{documentId}/content endpoint. The endpoint lets you download the entire extracted plain text of a document.

2022-03-15

Sequences

Changed

  • Changed sequences column limits. Old limit of maximum total 200 columns limits is updated to maximum 400 total columns, maximum 400 numeric columns and maximum 200 string columns.

2022-03-02

Sequences

Added

2022-02-08

Time series

Changed

  • Marked isStep parameter to be editable (i.e. removed description stating it is not updatable) in POST /timeseries/create.

Added

2022-02-07

Documents

Added

2022-01-25

Documents

Added

2022-01-24

Time series

Added

  • Added optional ignoreUnknownIds parameter to POST /sequences/delete. Setting this to true will prevent the operation from failing if one or more of the given sequences do not exist; instead, those given sequences that do exist will be deleted.

2021-12-07

Transformations

Added

2021-11-22

Contextualization

Added

  • Added diagram detect endpoint to v1 to detect annotations in engineering diagrams
  • Added diagram detect results endpoint to v1 to get the results from an engineering diagram detect job
  • Added diagram convert endpoint to v1 to create interactive engineering diagrams in SVG format with highlighted annotations
  • Added diagram convert results endpoint to v1 to get the results for a job converting engineering diagrams to SVGs

2021-11-17

3D

Added

  • Added dataSetId support to 3D models enabling data access scoping of 3D data

2021-10-13

Raw

Changed

  • To align with Microsoft Azure clusters, table and database names are now sensitive to trailing spaces also in Google Cloud Platform clusters.

2021-10-05

Extraction Pipelines

Added

  • New Extraction Pipelines resource to document extractors and monitor the status of data ingestion to make sure reliable and trustworthy data are flowing into the CDF data sets.
  • API endpoints for creating, managing, and deleting extraction pipelines. Capture common attributes around extractors such as owners, contacts, schedule, destination RAW databases, and data set. Document structured metadata in the form of key-value attributes as well unstructured documentation attribute that supports Markdown (rendered as Markdown in Fusion).
  • Extraction Pipelines Runs are CDF objects to store statuses related to an extraction pipeline. The supported statuses are: success, failure and seen. They enable extractor developers to report status and error message after ingesting data. As well enables for reporting heartbeat through seen status by the extractor to easily identify issues related to crushed applications and scheduling issues.

2021-09-28

Sequences

Added

Time series

Added

2021-08-18

IAM (Identity and access management)

Added

Added sessions to v1. Sessions let you securely delegate access to CDF resources for CDF services (such as Functions) by an external principal and for an extended time.

2021-08-12

Relationships

Added

2021-07-01

3D

Added

  • Added filter3dNodes endpoint to allow for more advanced filtering on node metadata

2021-06-29

Labels

Added

2021-06-08

Sequences

Added

2021-06-01

Assets

Added

2021-04-28

Time series

Changed granularity limits on hour aggreagates

You can now ask for a granularity of up to 100000 hours (previously 48 hours), both in normal aggregates and in synthetic time series.

2021-04-12

IAM (Identity and access management)

Added

2021-04-06

Authentication

Deprecated

We are deprecating authentication via CDF service accounts and API keys, and user sign-in via /login, in favor of registering applications and services with your IdP (identity provider) and using OpenID Connect and the IdP framework to manage CDF access securely.

The legacy authentication flow is available for customers using Cognite Data Fusion (CDF) on GCP until further notice. We strongly encourage customers to adopt the new authentication flows as soon as possible.

The following API endpoints are deprecated:

  • /api/v1/projects/*/apikeys
  • /api/v1/projects/*/serviceaccounts
  • /login
  • /logout
  • /api/v1/projects/*/groups/serviceaccounts *

*only the sub-resources for listing, adding, and removing members of groups.

2021-03-22

CDF API 0.5, 0.6 reached their end-of-life after its initial deprecation announcement in Summer 2019.

2021-03-10

3D

Added

  • Added partition parameter to the List 3D Nodes endpoint for supporting parallel requests.
  • Added sortByNodeId parameter to the List 3D Nodes endpoint, improving request latency in most cases if set to true.

2021-02-26

Entity matching

Fixed

  • Fixed a bug in the documentation for Entity matching. The (job) status shall be capitalized string.

2020-12-22

Files

Added

  • New field fileType inside derivedFields to refer to a pre-defined subset of MIME types.
  • New filter fileType inside derivedFields to find files with a pre-defined subset of MIME types.

2020-10-20

Files

Added

  • New field geoLocation to refer to the geographic location of the file.
  • New filter geoLocation to find files matching a certain geographic location.

To learn how to leverage new geoLocation features, follow our guide.

2020-08-29

Files

Added

  • New field directory referring to the directory in the source containing the file.
  • New filter directoryPrefix allows you to find Files matching a certain directory prefix.

2020-08-05

Files

Added

  • New field labels allows you to attach labels to Files upon creation or updating.
  • New filter labels allows you to find Files that have been annotated with specific labels.

2020-07-08

IAM (Identity and access management)

Added

  • New project field applicationDomains. If this field is set, users only sign in to the project through applications hosted on a whitelisted domain. Read more.

2020-07-01

Events

Added

  • New aggregation uniqueValues allows you to find different types, subtypes of events in your project.

2020-06-29

Labels

Added

  • New data organization resource: labels. Manage terms that you can use to annotate and group assets.

Assets

Added

  • New filter labels allows you to find resources that have been annotated with specific labels.

Time series

Added

2020-04-28

Events

Added

  • New filtering capabilities to find open events endTime=null.
  • New filtering capabilities to find all events intersecting a timespan using activeAtTime.

2020-03-12

General

Added

  • New data organization resource: data sets. Document and track data lineage, ensure data integrity, and allow 3rd parties to write their insights securely back to your Cognite Data Fusion (CDF) project.
  • New attribute datasetId introduced in assets, files, events, time series and sequences.
  • New filter dataSetIds allows you to narrow down results to resources containing datasetId by a list of ids or externalIds of a data set. Supported by assets, files, events, time series and sequences.
  • We have added a new aggregation endpoint for time series. With this endpoint, you can find out how many results in a tenant meet the criteria of a filter. We will expand this feature to add more aggregates than count.

Groups

Added

  • Introduced a new capability: datasetsAcl for managing access to data set resources.
  • New scope datasetScope for assets, files, events, time series and sequences ACLs. Allows you to scope down access to resources contained within a specified set of data sets.

2020-03-10

3D

Fixed

  • We fixed a bug in the documentation of 3D model revisions. Applications should anticipate that 3D nodes may not have a bounding box.

2020-02-25

Assets

Added

  • We have added a new aggregation endpoint for assets. With this endpoint, you can find out how many assets in a tenant meet the criteria of a filter. We will expand this feature to add more aggregates than count.

Events

Added

  • We have added a new aggregation endpoint for events. With this endpoint, you can find out how many events in a tenant meet the criteria of a filter. We will expand this feature to add more aggregates than count.

2020-02-12

Assets

Added

  • We have added new aggregation properties: depth and path. You can use the properties in the filter and retrieve endpoints.

2020-02-10

Assets

Added

  • Added the property parentExternalId which is returned for all assets which have a parent with a defined externalId.

2019-12-09

General

Added

  • Added assetSubtreeIds as a parameter to filter, search, and list endpoints for all core resources. assetSubtreeIds allows you to specify assets that are subtree roots, and then only retrieve resources that are related to assets within those subtrees.

2019-12-04

Assets

Added

  • Added the ability to filter assets by parent external IDs.

2019-11-12

Access control

Removed

  • Groups can no longer be created with a permissions field in v0.5.

2019-10-31

Assets

Added

  • Asset search now has a search.query parameter. This uses an improved search algorithm that tries a wider range of variations of the input terms and gives much better relevancy ranking than the existing search.name and search.description fields.

Time Series

Changed

  • The search.query parameter for time series search now uses an improved search algorithm that tries a wider range of variations of the input terms, and gives much better relevancy ranking.

2019-10-23

Files

Added

  • Added support for updating the mimeType for existing files in files/update requests.

2019-10-18

Time Series

Added

  • Time series expanded their filtering capabilities with new Filter time series endpoint, allowing for additional filtering by:

    • Name
    • Unit
    • Type of time series: string or step series
    • Metadata objects
    • ExternalId prefix filtering
    • Create and last updated time ranges

    Endpoint in addition support pagination and partitioning. Check out detailed API documentation here.

2019-10-02

Sequences

Added

  • Introducing the new sequences core resource type that lets you store numerically indexed multi-column rows of data. Connect your sequences to physical assets and to their source systems through externalId and metadata support. Read more here.

2019-09-30

3D

Added

  • Added endpoint to get multiple nodes for a 3D model by their IDs.
  • Added endpoint to get asset mappings for multiple node IDs or asset IDs.

2019-09-23

Files

Added

  • Added support for filter on rootAssetIds in files GET /files (using query parameter) and POST /files/list (in request body).

2019-09-16

Assets and Events

Added

  • Added support for partition in /assets and /events to support parallel retrieval. See guide for usage here

2019-08-22

3D

Added

  • Added the query parameter intersectsBoundingBox to the list asset mappings endpoint. The parameter filters asset mappings to the assets where the bounding box intersects (or is contained within) the specified bounding box.

2019-08-21

Files

Added

  • Added support for sourceCreatedTime and sourceModifiedTime fields in files v1 endpoints.

Assets

Added

  • Allow the parent asset ID to be updated. The root asset ID must be preserved, and you can not convert a non-root asset to a root asset or vice versa.
  • Support for ignoreUnknownIds when deleting assets.

2019-08-15

3D

Added

  • Properties field for 3D nodes, extracted from uploaded 3D files.
  • Ability to filter nodes with a specific set of properties.

2019-07-24

Files

Changed

  • Allow lookup of names with length up to 256 characters (was 50) for GET /files and POST /files/search operations.
  • Allow creating and retrieving files with mimeType length up to 256 characters (was 64).

2019-07-15

Time series

Added

  • Added query parameter rootAssetIds to list time series endpoint. Returns time series that are linked to an asset that has one of the root assets as an ancestor.

2019-07-11

List of changes for initial API v1 release in comparison to previous version - API 0.5

General

Added

  • Support for externalId added across resource types. externalId lets you define a unique ID for a data object. Learn more: External IDs
  • externalIdPrefix added as a parameter to the list events, assets and files operations.
  • Richer filtering on the list assets, files and events operations.
  • Search, list and filter operations for assets, events and files now support filtering on source and metadata field values.

Changed

  • Core resources standardize on HTTP methods and URI naming for common operations such as search, partial updates, delete, list and filter
  • API responses are no longer wrapped in a top level data object.
  • Standardized pagination across resources through limit, cursor and nextCursor parameters.
  • The limit parameter no longer implicitly rounds down requested page size to maximum page size.
  • Standardized error responses and codes across all resources. Errors across CDF can be parsed into a single model.
  • Overall improvements to reference documentation. Including documented input constraints, required fields, individual attribute descriptions.

Removed

  • The sourceId field has been removed from resources. Use externalId instead of sourceId+source to define unique IDs for data objects.
  • Sorting is removed from the search operations for files, assets, events and time series. Results are sorted by relevance.
  • offset and previousCursor parameters are no longer supported for pagination across resources.
  • Fetching an asset subtree is no longer supported by files, assets, events and time series.

Assets

Added

  • Ability to select only root assets though new root filter.
  • Added the rootId field to specify the top element in an asset hierarchy.
  • Added the ability to filter by the root asset ID. This allows you to scope queries for one or many asset hierarchies.
  • List Assets allows for filtering assets belonging to set of root assets, specified by list of asset internal ids. New query parameter: rootIds.
  • Filter and Search Assets allows or filtering assets belonging to a set of root assets, specified by combination of internal and external asset identifiers. New body attribute: rootIds.

Changed

  • Updating a single asset is no longer supported through a separate endpoint. Use the update multiple endpoint instead.
  • Delete assets by default removes only leaf assets (assets without children). New parameter 'recursive' allows for enabling recursive removal of the entire subtree of the asset pointed by ID (API 0.5 behaviour).

Removed

  • Overwriting assets is no longer supported.
  • Filtering assets by their complete description is no longer supported.
  • Locating assets fuzzily by name has been removed. Instead, search for assets on the name property.
  • When searching assets, querying over both name and description in the same query is no longer supported.
  • The experimental query parameter boostName has been removed from the search for assets operation.
  • Removed the path and depth fields.

Events

Added

  • Events can now be filtered on asset ID in combination with other filters.
  • New filter rootAssetIds allows for narrowing down events belonging only to list or specified root assets. Supported by Filter and Search API

Removed

  • Events can no longer be filtered by empty description.
  • The 'dir' parameter has been removed from the search events operation.

Files

Added

  • Filtering files by assetIds in list files operations now support multiple assets in the same request.

Changed

  • Download file content has changed from HTTP GET to HTTP POST method.
  • We have renamed the fileType field to mimeType. The field now requires a MIME formatted string (e.g. text/plain).
  • We have renamed the uploadedAt field to uploadedTime.
  • Resumable is now the default behavior for file uploads.
  • Update metadata for single files is no longer supported by a separate operation. Instead, use the update multiple operation.

Removed

  • Replace files metadata endpoint has been removed.
  • Directory has been removed as a property of files.
  • Updating the name or mimeType of a file through the update multiple files operation is no longer supported.
  • Query parameter for specifying the sort direction has been removed from list all files operations.

Raw

Changed

  • Raw has changed structure to become resource-oriented. The URL structure has changed.
  • Recursively delete of tables and rows when deleting a database is now the default behavior without a control parameter.

Time series

Added

  • Support for adding datapoints by id and externalId of time series. Adding datapoints to time series by name has been removed.
  • Add ability to update the new externalId attribute for time series.
  • Allow to set externalId during creation of time series. ExternalId requires uniqueness across time series.
  • Consolidate multiple APIs to allow adding datapoints into a single endpoint. Allows datapoints to be added to multiple time series at the same time.
  • Retrieve data points by using id and externalId of the time series.
  • Time series created through API v1 are not discoverable by API 0.3, 0.4, 0.5 and 0.6 by default. Introduce the option to enable this compatibility by setting new attribute - legacyName on time series creation. Value is required to be unique.

Changed

  • Get latest datapoints has been reworked. Introduces support for id and externalId lookup as well retrieval for multiple time series within the same request.
  • Time series name is no longer limited by uniqueness. Note that time series (meta objects) created by API v1 will not be discoverable by older API versions.
  • Delete time series endpoint has been redesigned to allow deletion of multiple time series by id and externalId.
  • Delete single and multiple datapoints endpoint has been redesigned and consolidated into a single endpoint. New delete allows selection of multiple time series and time ranges by id and externalId. Selecting by name is no longer available.
  • Update multiple time series restructured to support lookup by externalId.
  • Retrieve time series by ID endpoint restructured adding the ability to get time series by externalId.
  • Set limit for data point value to min -1E100, max 1E100.

Removed

  • Experimental feature for performing calculations across multiple time series (synthetic time series), function and alias attributes are no longer available.
  • The experimental query parameter boostName has been removed from search operation.
  • Short names for aggregate functions are no longer supported.
  • Ability to remove time series by name have been removed as names are no longer unique identifiers.
  • Select multiple time series and time ranges by name is no longer available.
  • The ability to update isString and isStep attributes is removed. The attributes are not intended to be modified after creation of time series.
  • The endpoint for updating single time series is removed. Use the update multiple time series endpoint instead.
  • Remove ability to overwrite time series object by id. Use the update multiple time series endpoint instead.
  • The ability to retrieve time series matching by name has been removed. Use externalId instead.
  • The ability to retrieve by id from a single time series has been removed. Use retrieve multiple datapoints for multiple time series instead.
  • The ability to retrieve time-aligned datapoints through "dataframe" API has been removed. Similar functionality is available through our supported SDKs.
  • The ability to add datapoints to time series by name has been removed.
  • The ability to look up by time series name has been removed.

IAM (Identity and access management)

Added

  • The login status endpoint includes the ID of the API key making the request (new attribute: apiKeyId), if the request used an API key.

Changed

  • The user resource type has been replaced with service accounts. Users from previous API versions are equivalent to service accounts.
  • Adding, listing and removing users from a group has been replaced by equivalent operations for service accounts.
  • Retrieve project returns a single object instead of a list.
  • API keys endpoints for list/create rename userId attribute to serviceAccountId.

Removed

  • List and create groups no longer use the permissions and source attributes.

3D

Added

  • New 3D API lets you upload and process 3D models. Supported format: FBX.
  • Ability to create and maintain multiple revisions for the 3D models.
  • API for mapping relationships between 3D model nodes and asset hierarchy.

Projects

Projects are used to isolate data in CDF from each other. All objects in CDF belong to a single project, and objects in different projects are generally isolated from each other.

Create a project

Creates new projects given project details. This functionality is currently only available for Cognite and re-sellers of Cognite Data Fusion. Please contact Cognite Support for more information.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of new project specifications

required
Array of objects (NewProjectSpec)

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "name": "Open Industrial Data",
  • "urlName": "publicdata"
}

List projects

The list of all projects that the user has the 'list projects' capability in. The user may not have access to any resources in the listed projects, even if they have access to list the project itself.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code

Responses

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Retrieve a project

Retrieves information about a project given the project URL name.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
projectName
required
string
Example: publicdata

The CDF project name, equal to the project variable in the server URL.

Responses

Request samples

const projectInfo = await client.projects.retrieve('publicdata');

Response samples

Content type
application/json
{
  • "name": "Open Industrial Data",
  • "urlName": "publicdata",
  • "defaultGroupId": 123871937,
  • "authentication": {
    • "validDomains": [
      ],
    • "applicationDomains": [
      ]
    },
  • "oidcConfiguration": {
    • "jwksUrl": "string",
    • "tokenUrl": "string",
    • "issuer": "string",
    • "audience": "string",
    • "skewMs": 0,
    • "accessClaims": [
      ],
    • "scopeClaims": [
      ],
    • "logClaims": [
      ],
    • "isGroupCallbackEnabled": false,
    • "identityProviderScope": "string"
    }
}

Update a project

Updates the project configuration.

Warning: Updating a project will invalidate active sessions within that project.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
projectName
required
string
Example: publicdata

The CDF project name, equal to the project variable in the server URL.

Request Body schema: application/json

Object with updated project configuration.

required
object (ProjectUpdateObjectDTO)

Contains the instructions on how to update the project. Note: azureADConfiguration, oidcConfiguration and oAuth2Configuration are mutually exclusive

Responses

Request samples

Content type
application/json
{
  • "update": {
    • "name": {
      },
    • "defaultGroupId": {
      },
    • "validDomains": {
      },
    • "applicationDomains": {
      },
    • "authenticationProtocol": {
      },
    • "azureADConfiguration": {
      },
    • "oAuth2Configuration": {
      },
    • "oidcConfiguration": {
      }
    }
}

Response samples

Content type
application/json
{
  • "name": "Open Industrial Data",
  • "urlName": "publicdata",
  • "defaultGroupId": 123871937,
  • "authentication": {
    • "validDomains": [
      ],
    • "applicationDomains": [
      ]
    },
  • "oidcConfiguration": {
    • "jwksUrl": "string",
    • "tokenUrl": "string",
    • "issuer": "string",
    • "audience": "string",
    • "skewMs": 0,
    • "accessClaims": [
      ],
    • "scopeClaims": [
      ],
    • "logClaims": [
      ],
    • "isGroupCallbackEnabled": false,
    • "identityProviderScope": "string"
    }
}

Groups

Groups are used to give principals the capabilities to access CDF resources. One principal can be a member in multiple groups and one group can have multiple members. Note that having more than 20 groups per principal is not supported and may result in login issues.

Create groups

Creates one or more named groups, each with a set of capabilities.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of groups to create.

required
Array of objects (GroupSpec)

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete groups

Deletes the groups with the given IDs.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of group IDs to delete

items
required
Array of integers <int64> non-empty unique [ items <int64 > ]

Responses

Request samples

Content type
application/json
{
  • "items": [
    • 23872937137,
    • 1238712837,
    • 128371973
    ]
}

Response samples

Content type
application/json
{ }

List groups

Retrieves a list of groups the asking principal a member of. Principals with groups:list capability can optionally ask for all groups in a project.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
all
boolean
Default: false

Whether to get all groups, only available with the groups:list acl.

Responses

Request samples

const groups = await client.groups.list({ all: true });

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Security categories

Manage security categories for a specific project. Security categories can be used to restrict access to a resource. Applying a security category to a resource means that only principals (users or service accounts) that also have this security category can access the resource. To learn more about security categories please read this page.

Create security categories

Creates security categories with the given names. Duplicate names in the request are ignored. If a security category with one of the provided names exists already, then the request will fail and no security categories are created.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of categories to create

required
Array of objects (SecurityCategorySpecDTO) non-empty

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete security categories

Deletes the security categories that match the provided IDs. If any of the provided IDs does not belong to an existing security category, then the request will fail and no security categories are deleted.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of security category IDs to delete.

items
required
Array of integers <int64> non-empty unique [ items <int64 > ]

Responses

Request samples

Content type
application/json
{
  • "items": [
    • 23872937137,
    • 1238712837,
    • 128371973
    ]
}

Response samples

Content type
application/json
{ }

List security categories

Retrieves a list of all security categories for a project.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
sort
string
Default: "ASC"
Enum: "ASC" "DESC"

Sort descending or ascending.

cursor
string

Cursor to use for paging through results.

limit
integer <int32> <= 1000
Default: 25

Return up to this many results. Maximum is 1000. Default is 25.

Responses

Request samples

const securityCategories = await client.securityCategories.list({ sort: 'ASC' });

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Sessions

Sessions are used to maintain access to CDF resources for an extended period of time. The methods available to extend a sessions lifetime are client credentials and token exchange. Sessions depend on the project OIDC configuration and may become invalid in the following cases

  • Project OIDC configuration has been updated through the update project endpoint. This action invalidates all of the project's sessions.

  • The session was invalidated through the identity provider.

Create sessions

Create sessions

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

A request containing the information needed to create a session.

Array of CreateSessionWithClientCredentialsRequest (object) or CreateSessionWithTokenExchangeRequest (object) (CreateSessionRequest) = 1 items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

List sessions

List all sessions in the current project.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
status
string
Enum: "ready" "active" "cancelled" "revoked" "access_lost"

If given, only sessions with the given status are returned.

cursor
string

Cursor to use for paging through results.

limit
integer <int32> <= 1000
Default: 25

Return up to this many results. Maximum is 1000. Default is 25.

Responses

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string",
  • "previousCursor": "string"
}

Retrieve sessions with given IDs

Retrieves sessions with given IDs. The request will fail if any of the IDs does not belong to an existing session.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of session IDs to retrieve

required
Array of objects [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Revoke sessions

Revoke access to a session. Revocation of a session may in some cases take up to 1 hour to take effect.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

A request containing the information needed to revoke sessions.

Array of objects (RevokeSessionRequest)

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Token

Access tokens issued by an IdP (Azure AD, Google, etc.) are used to access CDF resources.

Inspect

Inspect CDF access granted to an IdP issued token

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code

Responses

Response samples

Content type
application/json
{
  • "subject": "string",
  • "projects": [
    • {
      }
    ],
  • "capabilities": [
    • {
      }
    ]
}

User profiles

User profiles is an authoritative source of core user profile information (email, name, job title, etc.) for principals based on data from the identity provider configured for the CDF project.

User profiles are first created (usually within a few seconds) when a principal issues a request against a CDF API. We currently don't support automatic exchange of user identity information between the identity provider and CDF, but the profile data is updated regularly with the latest data from the identity provider for the principals issuing requests against a CDF API.

Note that the user profile data is mutable, and any updates in the external identity provider may also cause updates in this API. Therefore, you cannot use profile data, for example a user's email, to uniquely identify a principal. The exception is the userIdentifier property which is guaranteed to be immutable.

Get the user profile of the principal issuing the request

Retrieves the user profile of the principal issuing the request. If a principal doesn't have a user profile, you get a not found (404) response code.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code

Responses

Response samples

Content type
application/json
{
  • "userIdentifier": "abcd",
  • "givenName": "Jane",
  • "surname": "Doe",
  • "email": "jane.doe@example.com",
  • "displayName": "Jane Doe",
  • "jobTitle": "Software Engineer",
  • "lastUpdatedTime": 0
}

List all user profiles

List all user profiles in the current project. This operation supports pagination by cursor. The results are ordered alphabetically by name.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 25

Limits the number of results to be returned. The server returns no more than 1000 results even if the specified limit is larger. The default limit is 25.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

Responses

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Retrieve one or more user profiles by ID

Retrieve one or more user profiles indexed by the user identifier in the same CDF project.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Specify a maximum of 1000 unique IDs.

Array of objects (UserIdentifier)

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Search user profiles

Search user profiles in the current project. The result set ordering and match criteria threshold may change over time. This operation does not support pagination.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Query for user profile search.

object
limit
integer <int32> [ 1 .. 1000 ]
Default: 25

<- Limits the maximum number of results to be returned by single request. The default is 25.

Responses

Request samples

Content type
application/json
{
  • "search": {
    • "name": "string"
    },
  • "limit": 25
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Assets

The assets resource type stores digital representations of objects or groups of objects from the physical world. Assets are organized in hierarchies. For example, a water pump asset can be a part of a subsystem asset on an oil platform asset.

Rate and concurrency limits

Rate and concurrency limits apply to some of the endpoints. If a request exceeds one of the limits, it will be throttled with a 429: Too Many Requests response. More on limit types and how to avoid being throttled is described here.

Following limits apply to the List assets, Filter assets, Aggregate assets and Search assets endpoints. These limits apply to all endpoints simultaneously, i.e. requests made to different endpoints are counted together. Please note the additional conditions that apply to the Aggregate assets endpoint, as this endpoint provides the most resource-consuming operations.

Limit Per project Per user (identity)
Rate 30 rps total
out of which no more than 15 rps to Aggregate
20 rps
out of which no more than 10 rps to Aggregate
Concurrency 15 parallel requests
out of which no more than 6 to Aggregate
10 parallel requests
out of which no more than 4 to Aggregate

Aggregate assets

The aggregation API lets you compute aggregated results on assets, such as getting the count of all assets in a project, checking different names and descriptions of assets in your project, etc.

Aggregate filtering

Filter (filter & advancedFilter) data for aggregates

Filters behave the same way as for the Filter assets endpoint. In text properties, the values are aggregated in a case-insensitive manner.

aggregateFilter to filter aggregate results

aggregateFilter works similarly to advancedFilter but always applies to aggregate properties. For instance, in case of an aggregation for the source property, only the values (aka buckets) of the source property can be filtered out.

Request throttling

This endpoint is meant for data analytics/exploration usage and is not suitable for high load data retrieval usage.
It is a subject of the new throttling schema (limited request rate and concurrency). Please check Assets resource description for more information.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
One of
aggregate
string
Value: "count"

Type of aggregation to apply. count: Get approximate number of Assets matching the filters.

(BoolFilter (and (object) or or (object) or not (object))) or (LeafFilter (equals (object) or in (object) or range (object) or prefix (object) or exists (object) or containsAny (object) or containsAll (object) or search (object)))

A filter DSL (Domain Specific Language) to define advanced filter queries.

See more information about filtering DSL here.

Supported properties:

Property Type
["labels"] array of [string]
["createdTime"] number
["dataSetId"] number
["id"] number
["lastUpdatedTime"] number
["parentId"] number
["rootId"] number
["description"] string
["externalId"] string
["metadata"] string
["metadata", "someCustomKey"] string
["name"] string
["source"] string

Note: Filtering on the ["metadata"] property has the following logic: If a value of any metadata keys in an asset matches the filter, the asset matches the filter.

object (Filter)

Filter on assets with strict matching.

Responses

Request samples

Content type
application/json
Example
{
  • "aggregate": "count",
  • "advancedFilter": {
    • "or": [
      ]
    },
  • "filter": {
    • "name": "string",
    • "parentIds": [
      ],
    • "parentExternalIds": [
      ],
    • "rootIds": [
      ],
    • "assetSubtreeIds": [
      ],
    • "dataSetId": {
      },
    • "dataSetIds": [
      ],
    • "metadata": {
      },
    • "source": "string",
    • "createdTime": {
      },
    • "lastUpdatedTime": {
      },
    • "root": true,
    • "externalIdPrefix": "my.known.prefix",
    • "labels": {
      },
    • "geoLocation": {
      }
    }
}

Response samples

Content type
application/json
Example
{
  • "items": [
    • {
      }
    ]
}

Create assets

You can create a maximum of 1000 assets per request.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of the assets to create. You can create a maximum of 1000 assets per request.

required
Array of objects (DataExternalAssetItem) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete assets

Delete assets. By default, recursive=false and the request would fail if attempting to delete assets that are referenced as parent by other assets. To delete such assets and all its descendants, set recursive to true. The limit of the request does not include the number of descendants that are deleted.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
required
Array of AssetInternalId (object) or AssetExternalId (object) (AssetIdEither) [ 1 .. 1000 ] items
recursive
boolean
Default: false

Recursively delete all asset subtrees under the specified IDs.

ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "recursive": false,
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{ }

Filter assets

Retrieve a list of assets in the same project. This operation supports pagination by cursor. Apply Filtering and Advanced filtering criteria to select a subset of assets.

Advanced filtering

Advanced filter lets you create complex filtering expressions that combine simple operations, such as equals, prefix, exists, etc., using boolean operators and, or, and not. It applies to basic fields as well as metadata.

See the advancedFilter attribute in the example.

See more information about filtering DSL here.

Supported leaf filters

Leaf filter Supported fields Description
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 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 value.
{"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"], ["description"] Introduced to provide functional parity with /assets/search endpoint.
{"search": {"property": ["property"], "value": "example"}}

The search leaf filter provides functional parity with the /assets/search endpoint. It's available only for the ["description"] and ["name"] properties. When specifying only this filter with no explicit ordering, behavior is the same as of the /assets/search/ endpoint without specifying filters. Explicit sorting overrides the default ordering by relevance. It's possible to use the search leaf filter as any other leaf filter for creating complex queries.

See the search filter in the advancedFilter attribute in the example.

advancedFilter attribute limits

  • filter query max depth: 10
  • filter query max number of clauses: 100
  • and and or clauses must have at least one element
  • property array of each leaf filter has the following limitations:
    • number of elements in the array is in the range [1, 2]
    • elements must not be blank
    • each element max length is 128 symbols
    • property array must match one of the existing properties (static or dynamic metadata).
  • 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 a primitive type (number, string)
  • range filter must have at least one of gt, gte, lt, lte attributes. But gt is mutually exclusive to gte, while lt is mutually exclusive to lte. At least one of the bounds must be specified.
  • gt, gte, lt, lte in the range filter must be a primitive value
  • search filter value must not be blank and the length must be in the range [1, 128]
  • filter query may have maximum 2 search leaf filters
  • maximum leaf filter string value length is different depending on the property the filter is using:
    • externalId - 255
    • name - 128 for the search filter and 255 for other filters
    • description - 128 for the search filter and 255 for other filters
    • labels item - 255
    • source - 128
    • any metadata key - 128

Sorting

By default, assets are sorted by id in the ascending order. Use the search leaf filter to sort the results by relevance. Sorting by other fields can be explicitly requested. The order field is optional and defaults to desc for _score_ and asc for all other fields. The nulls field is optional and defaults to auto. auto is translated to last for the asc order and to first for the desc order by the service. Partitions are done independently of sorting; there's no guarantee of the sort order between elements from different partitions.

See the sort attribute in the example.

Null values

In case the nulls attribute has the auto value or the attribute isn't specified, null (missing) values are considered to be bigger than any other values. They are placed last when sorting in the asc order and first when sorting in desc. Otherwise, missing values are placed according to the nulls attribute (last or first), and their placement doesn't depend on the order value. Values, such as empty strings, aren't considered as nulls.

Sorting by score

Use a special sort property _score_ when sorting by relevance. The more filters a particular asset matches, the higher its score is. This can be useful, for example, when building UIs. Let's assume we want exact matches to be be displayed above matches by prefix as in the request below. An asset named pump will match both equals and prefix filters and, therefore, have higher score than assets with names like pump valve that match only prefix filter.

"advancedFilter" : {
  "or" : [
    {
      "equals": {
        "property": ["name"], 
        "value": "pump"
      }
    },
    {
      "prefix": {
        "property": ["name"], 
        "value": "pump"
      }
    }
  ]
},
"sort": [
  {
    "property" : ["_score_"]
  }
]

Request throttling

This endpoint is meant for data analytics/exploration usage and is not suitable for high load data retrieval usage. It is a subject of the new throttling schema (limited request rate and concurrency). Please check Assets resource description for more information.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
object (Filter)

Filter on assets with strict matching.

(BoolFilter (and (object) or or (object) or not (object))) or (LeafFilter (equals (object) or in (object) or range (object) or prefix (object) or exists (object) or containsAny (object) or containsAll (object) or search (object)))

A filter DSL (Domain Specific Language) to define advanced filter queries.

See more information about filtering DSL here.

Supported properties:

Property Type
["labels"] array of [string]
["createdTime"] number
["dataSetId"] number
["id"] number
["lastUpdatedTime"] number
["parentId"] number
["rootId"] number
["description"] string
["externalId"] string
["metadata"] string
["metadata", "someCustomKey"] string
["name"] string
["source"] string

Note: Filtering on the ["metadata"] property has the following logic: If a value of any metadata keys in an asset matches the filter, the asset matches the filter.

limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Limits the number of results to return.

Array of objects (AssetSortProperty) [ 1 .. 2 ] items

Sort by array of selected properties.

cursor
string
aggregatedProperties
Array of strings (AggregatedProperty)
Items Enum: "childCount" "path" "depth"

Set of aggregated properties to include

partition
string (Partition)

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.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "name": "string",
    • "parentIds": [
      ],
    • "parentExternalIds": [
      ],
    • "rootIds": [
      ],
    • "assetSubtreeIds": [
      ],
    • "dataSetId": {
      },
    • "dataSetIds": [
      ],
    • "metadata": {
      },
    • "source": "string",
    • "createdTime": {
      },
    • "lastUpdatedTime": {
      },
    • "root": true,
    • "externalIdPrefix": "my.known.prefix",
    • "labels": {
      },
    • "geoLocation": {
      }
    },
  • "advancedFilter": {
    • "or": [
      ]
    },
  • "limit": 100,
  • "sort": [
    • {
      },
    • {
      }
    ],
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
  • "aggregatedProperties": [
    • "childCount"
    ],
  • "partition": "1/10"
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

List assets

List all assets, or only the assets matching the specified query.

Request throttling

This endpoint is meant for data analytics/exploration usage and is not suitable for high load data retrieval usage. It is a subject of the new throttling schema (limited request rate and concurrency). Please check Assets resource description for more information.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

includeMetadata
boolean
Default: true

Whether the metadata field should be returned or not.

name
string (AssetName) [ 1 .. 140 ] characters

The name of the asset.

parentIds
string <jsonArray(int64)> (JsonArrayInt64)
Example: parentIds=[363848954441724, 793045462540095, 1261042166839739]

List only assets that have one of the parentIds as a parent. The parentId for root assets is null.

parentExternalIds
string <jsonArray(string)> (JsonArrayString)
Example: parentExternalIds=[externalId_1, externalId_2, externalId_3]

List only assets that have one of the parentExternalIds as a parent. The parentId for root assets is null.

rootIds
string <jsonArray(int64)> (JsonArrayInt64)
Deprecated
Example: rootIds=[363848954441724, 793045462540095, 1261042166839739]

This parameter is deprecated. Use assetSubtreeIds instead. List only assets that have one of the rootIds as a root asset. A root asset is its own root asset.

assetSubtreeIds
string <jsonArray(int64)> (JsonArrayInt64)
Example: assetSubtreeIds=[363848954441724, 793045462540095, 1261042166839739]

List only assets that are in a subtree rooted at any of these assetIds (including the roots given). If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.

assetSubtreeExternalIds
string <jsonArray(string)> (JsonArrayString)
Example: assetSubtreeExternalIds=[externalId_1, externalId_2, externalId_3]

List only assets that are in a subtree rooted at any of these assetExternalIds. If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.

source
string <= 128 characters

The source of the asset, for example which database it's from.

root
boolean
Default: false

Whether the filtered assets are root assets, or not. Set to True to only list root assets.

minCreatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

maxCreatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

minLastUpdatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

maxLastUpdatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

externalIdPrefix
string (CogniteExternalIdPrefix) <= 255 characters
Example: externalIdPrefix=my.known.prefix

Filter by this (case-sensitive) prefix for the external ID.

partition
string
Example: partition=1/10

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.

Responses

Request samples

const assets = await client.assets.list({ filter: { name: '21PT1019' } });

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Retrieve an asset by its ID

Retrieve an asset by its ID. If you want to retrieve assets by externalIds, use Retrieve assets instead.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
id
required
integer <int64> (CogniteInternalId) [ 1 .. 9007199254740991 ]

A server-generated ID for the object.

Responses

Request samples

const assets = await client.assets.retrieve([{id: 123}, {externalId: 'abc'}]);

Response samples

Content type
application/json
{
  • "createdTime": 0,
  • "lastUpdatedTime": 0,
  • "rootId": 1,
  • "aggregates": {
    • "childCount": 0,
    • "depth": 0,
    • "path": [
      ]
    },
  • "parentId": 1,
  • "parentExternalId": "my.known.id",
  • "externalId": "my.known.id",
  • "name": "string",
  • "description": "string",
  • "dataSetId": 1,
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    },
  • "source": "string",
  • "labels": [
    • {
      }
    ],
  • "geoLocation": {
    • "type": "Feature",
    • "geometry": {
      },
    • "properties": { }
    },
  • "id": 1
}

Retrieve assets

Retrieve assets by IDs or external IDs. If you specify to get aggregates, then be aware that the aggregates are eventually consistent.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

All provided IDs and external IDs must be unique.

required
Array of AssetInternalId (object) or AssetExternalId (object) (AssetIdEither) [ 1 .. 1000 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

aggregatedProperties
Array of strings (AggregatedProperty)
Items Enum: "childCount" "path" "depth"

Set of aggregated properties to include

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": false,
  • "aggregatedProperties": [
    • "childCount"
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Search assets

Fulltext search for assets based on result relevance. Primarily meant for human-centric use-cases, not for programs, since matching and ordering may change over time. Additional filters can also be specified. This operation doesn't support pagination.

Request throttling

This endpoint is meant for data analytics/exploration usage and is not suitable for high load data retrieval usage. It is a subject of the new throttling schema (limited request rate and concurrency). Please check Assets resource description for more information.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Search query

object (Filter)

Filter on assets with strict matching.

limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Limits the number of results to return.

object (Search)

Fulltext search for assets. Primarily meant for for human-centric use-cases, not for programs. The query parameter uses a different search algorithm than the deprecated name and description parameters, and will generally give much better results.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "parentIds": [
      ]
    },
  • "search": {
    • "name": "flow",
    • "description": "upstream"
    }
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Sync changes of assets (alpha feature)

Sync changes of assets. Use nextCursor to paginate through the results. This endpoint can continuously sync asset changes out of CDF using an internal change log. The change log follows the internal id of the asset, not the external id. It will include delete operations on the assets. Once asset is deleted, it won't appear again in the change log with the same internal id, even if it's recreated with the same external id. Once all assets have been synced out, the API will return an empty list of items and a valid nextCursor. The client should continue to poll the API with the nextCursor to get future updates and items. Client should preserve the latest returned nextCursor to avoid starting the sync from scratch. The API guarantees that the client will be able to sync to the latest version of all assets, however, doesn't guarantee that the client will see all changes in between. Resource data for deleted assets won't be included or if includeAssetData parameter is false. If you only want to sync out future changes of assets, you can use the onlyFuture parameter. The header cdf-version needs to be set to alpha to use this feature.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
header Parameters
cdf-version
string
Example: alpha

cdf version header. Use this to specify the requested CDF release.

Request Body schema: application/json
onlyFuture
boolean
Default: false

Initialise the cursor to only sync future updates. Only applicable when cursor isn't set.

includeAssetData
boolean
Default: true

Whether the asset resource data should be returned or not.

limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to return.

cursor
string

Responses

Request samples

Content type
application/json
{
  • "onlyFuture": false,
  • "includeAssetData": true,
  • "limit": 100,
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo"
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Update assets

Update the attributes of assets.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

All provided IDs and external IDs must be unique. Fields that aren't included in the request aren't changed.

required
Array of AssetChangeById (object) or AssetChangeByExternalId (object) (AssetChange) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Time series

A time series consists of a sequence of data points connected to a single asset. For example, a water pump asset can have a temperature time series that records a data point in units of °C every second.

A single asset can have several time series. The water pump could have additional time series measuring pressure within the pump, rpm, flow volume, power consumption, and more.Time series store data points as either numbers or strings. This is controlled by the is_string flag on the time series object. Numerical data points can be aggregated before they are returned from a query (e.g., to find the average temperature for a day). String data points, on the other hand, can't be aggregated by CDF but can store arbitrary information like states (e.g., “open”/”closed”) or more complex information (JSON).

Cognite stores discrete data points, but the underlying process measured by the data points can vary continuously. When interpolating between data points, we can either assume that each value stays the same until the next measurement or linearly changes between the two measurements. The isStep flag controls this on the time series object. For example, if we estimate the average over a time containing two data points, the average will either be close to the first (isStep) or close to the mean of the two (not isStep).

A data point stores a single piece of information, a number or a string, associated with a specific time. Data points are identified by their timestamps, measured in milliseconds since the unix epoch -- 00:00:00.000, January 1st, 1970. The time series service accepts timestamps in the range from 00:00:00.000, January 1st, 1900 through 23:59:59.999, December 31st, 2099 (in other words, every millisecond in the two centuries from 1900 to but not including 2100). Negative timestamps are used to define dates before 1970. Milliseconds is the finest time resolution supported by CDF, i.e., fractional milliseconds are not supported. Leap seconds are not counted.

Numerical data points can be aggregated before they are retrieved from CDF. This allows for faster queries by reducing the amount of data transferred. You can aggregate data points by specifying one or more aggregates (e.g., average, minimum, maximum) as well as the time granularity over which the aggregates should be applied (e.g., “1h” for one hour).

Aggregates are aligned to the start time modulo the granularity unit. For example, if you ask for daily average temperatures since Monday afternoon last week, the first aggregated data point will contain averages for Monday, the second for Tuesday, etc. Determining aggregate alignment without considering data point timestamps allows CDF to pre-calculate aggregates (e.g., to quickly return daily average temperatures for a year). Consequently, aggregating over 60 minutes can return a different result than aggregating over 1 hour because the two queries will be aligned differently. Asset references obtained from a time series - through its asset ID - may be invalid simply by the non-transactional nature of HTTP. They are maintained in an eventually consistent manner.

Aggregate time series

The aggregation API allows you to compute aggregated results from a set of time series, such as getting the number of time series in a project or checking what assets the different time series in your project are associated with (along with the number of time series for each asset). By specifying filter and/or advancedFilter, the aggregation will take place only over those time series that match the filters. filter and advancedFilter behave the same way as in the list endpoint.

The default behavior, when the aggregate field is not specified the request body, is to return the number of time series that match the filters (if any), which is the same behavior as when the aggregate field is set to count.

The following requests will both return the total number of time series whose name begins with pump:

{
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}}
}

and

{
  "aggregate": "count",
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}}
}

The response might be:

{"items": [{"count": 42}]}
Setting aggregate to uniqueValues and specifying a property in properties (this field is an array, but currently only supports one property) will return all unique values (up to a maximum of 1000) that are taken on by that property across all the time series that match the filters, as well as the number of time series that have each of those property values.

This example request finds all the unique asset ids that are referenced by the time series in your project whose name begins with pump:

{
  "aggregate": "uniqueValues",
  "properties": [{"property": ["assetId"]}],
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}}
}

The response might be the following, saying that 23 time series are associated with asset 18 and 107 time series are associated with asset 76:

{
  "items": [
    {"values": ["18"], "count": 23},
    {"values": ["76"], "count": 107}
  ]
}
Setting aggregate to cardinalityValues will instead return the approximate number of distinct values that are taken on by the given property among the matching time series.

Example request:

{
  "aggregate": "cardinalityValues",
  "properties": [{"property": ["assetId"]}],
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}}
}

The result is likely exact when the set of unique values is small. In this example, there are likely two distinct asset ids among the matching time series:

{"items": [{"count": 2}]}
Setting aggregate to uniqueProperties will return the set of unique properties whose property path begins with path (which can currently only be ["metadata"]) that are contained in the time series that match the filters.

Example request:

{
  "aggregate": "uniqueProperties",
  "path": ["metadata"],
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}}
}

The result contains all the unique metadata keys in the time series whose name begins with pump, and the number of time series that contains each metadata key:

{
  "items": [
    {"values": [{"property": ["metadata", "tag"]}], "count": 43},
    {"values": [{"property": ["metadata", "installationDate"]}], "count": 97}
  ]
}
Setting aggregate to cardinalityProperties will instead return the approximate number of different property keys whose path begins with path (which can currently only be ["metadata"], meaning that this can only be used to count the approximate number of distinct metadata keys among the matching time series).

Example request:

{
  "aggregate": "cardinalityProperties",
  "path": ["metadata"],
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}}
}

The result is likely exact when the set of unique values is small. In this example, there are likely two distinct metadata keys among the matching time series:

{"items": [{"count": 2}]}

The aggregateFilter field may be specified if aggregate is set to cardinalityProperties or uniqueProperties. The structure of this field is similar to that of advancedFilter, except that the set of leaf filters is smaller (in, prefix, and range), and that none of the leaf filters specify a property. Unlike advancedFilter, which is applied before the aggregation (in order to restrict the set of time series that the aggregation operation should be applied to), aggregateFilter is applied after the initial aggregation has been performed, in order to restrict the set of results.

Click here for more details about aggregateFilter.

When aggregate is set to uniqueProperties, the result set contains a number of property paths, each with an associated count that shows how many time series contained that property (among those time series that matched the filter and advancedFilter, if they were specified) . If aggregateFilter is specified, it will restrict the property paths included in the output. Let us add an aggregateFilter to the uniqueProperties example from above:

{
  "aggregate": "uniqueProperties",
  "path": ["metadata"],
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}},
  "aggregateFilter": {"prefix": {"value": "t"}}
}

Now, the result only contains those metadata properties whose key begins with t (but it will be the same set of metadata properties that begin with t as in the original query without aggregateFilter, and the counts will be the same):

{
  "items": [
    {"values": [{"property": ["metadata", "tag"]}], "count": 43}
  ]
}

Similarly, adding aggregateFilter to cardinalityProperties will return the approximate number of properties whose property key matches aggregateFilter from those time series matching the filter and advancedFilter (or from all time series if neither filter nor aggregateFilter are specified):

{
  "aggregate": "cardinalityProperties",
  "path": ["metadata"],
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}},
  "aggregateFilter": {"prefix": {"value": "t"}}
}

As we saw above, only one property matches:

{"items": [{"count": 1}]}

Note that aggregateFilter is also accepted when aggregate is set to cardinalityValues or cardinalityProperties. For those aggregations, the effect of any aggregateFilter could also be achieved via a similar advancedFilter. However, aggregateFilter is not accepted when aggregate is omitted or set to count.

Rate and concurrency limits

Rate and concurrency limits apply this endpoint. If a request exceeds one of the limits, it will be throttled with a 429: Too Many Requests response. More on limit types and how to avoid being throttled is described here.

Limit Per project Per user (identity)
Rate 15 requests per second 10 requests per second
Concurrency 6 concurrent requests 4 concurrent requests
Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Aggregates the time series that match the given criteria.

One of
(Boolean filter (and (object) or or (object) or not (object))) or (Leaf filter (equals (object) or in (object) or range (object) or prefix (object) or exists (object) or containsAny (object) or containsAll (object) or search (object))) (TimeSeriesFilterLanguage)

A filter DSL (Domain Specific Language) to define advanced filter queries.

At the top level, an advancedFilter expression is either a single Boolean filter or a single leaf filter. Boolean filters contain other Boolean filters and/or leaf filters. The total number of filters may be at most 100, and the depth (the greatest number of times filters have been nested inside each other) may be at most 10. The search leaf filter may at most be used twice within a single advancedFilter, but all other filters can be used as many times as you like as long as the other limits are respected.

object (Filter)
(Boolean filter (and (object) or or (object) or not (object))) or (Leaf filter (in (object) or range (object) or prefix (object))) (TimeSeriesAggregateFilter)

A filter DSL (Domain Specific Language) to define aggregate filters.

aggregate
string
Value: "count"

The count aggregation gets the number of time series that match the filter(s). This is the default aggregation, which will also be applied if aggregate is not specified.

Responses

Request samples

Content type
application/json
Example
{
  • "advancedFilter": {
    • "or": [
      ]
    },
  • "filter": {
    • "name": "string",
    • "unit": "string",
    • "isString": true,
    • "isStep": true,
    • "metadata": {
      },
    • "assetIds": [
      ],
    • "assetExternalIds": [
      ],
    • "rootAssetIds": [
      ],
    • "assetSubtreeIds": [
      ],
    • "dataSetIds": [
      ],
    • "externalIdPrefix": "my.known.prefix",
    • "createdTime": {
      },
    • "lastUpdatedTime": {
      }
    },
  • "aggregateFilter": {
    • "and": [
      ]
    },
  • "aggregate": "count"
}

Response samples

Content type
application/json
Example
{
  • "items": [
    • {
      }
    ]
}

Create time series

Creates one or more time series.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
required
Array of objects (PostTimeSeriesMetadataDTO) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete data points

Delete data points from time series.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

The list of delete requests to perform.

required
Array of QueryWithInternalId (object) or QueryWithExternalId (object) (DatapointsDeleteRequest) [ 1 .. 10000 ] items

List of delete filters.

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{ }

Delete time series

Deletes the time series with the specified IDs and their data points.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Specify a list of the time series to delete.

required
Array of QueryWithInternalId (object) or QueryWithExternalId (object) [ 1 .. 1000 ] items unique

List of ID objects.

ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{ }

Filter time series

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
["assetId"] number
["assetRootId"] number
["createdTime"] number
["dataSetId"] number
["id"] number
["lastUpdatedTime"] number
["isStep"] Boolean
["isString"] Boolean
["accessCategories"] array of strings
["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"]

Limits

The sort array must contain 1 to 2 elements.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
object (Filter)
(Boolean filter (and (object) or or (object) or not (object))) or (Leaf filter (equals (object) or in (object) or range (object) or prefix (object) or exists (object) or containsAny (object) or containsAll (object) or search (object))) (TimeSeriesFilterLanguage)

A filter DSL (Domain Specific Language) to define advanced filter queries.

At the top level, an advancedFilter expression is either a single Boolean filter or a single leaf filter. Boolean filters contain other Boolean filters and/or leaf filters. The total number of filters may be at most 100, and the depth (the greatest number of times filters have been nested inside each other) may be at most 10. The search leaf filter may at most be used twice within a single advancedFilter, but all other filters can be used as many times as you like as long as the other limits are respected.

limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Return up to this many results.

cursor
string
partition
string (Partition)

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.

Array of objects (TimeSeriesSortItem) [ 1 .. 2 ] items

Sort by array of selected properties.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "name": "string",
    • "unit": "string",
    • "isString": true,
    • "isStep": true,
    • "metadata": {
      },
    • "assetIds": [
      ],
    • "assetExternalIds": [
      ],
    • "rootAssetIds": [
      ],
    • "assetSubtreeIds": [
      ],
    • "dataSetIds": [
      ],
    • "externalIdPrefix": "my.known.prefix",
    • "createdTime": {
      },
    • "lastUpdatedTime": {
      }
    },
  • "advancedFilter": {
    • "or": [
      ]
    },
  • "limit": 100,
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
  • "partition": "1/10",
  • "sort": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Insert data points

Insert data points into a time series. You can do this for multiple time series. If you insert a data point with a timestamp that already exists, it will be overwritten with the new value.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema:

The datapoints to insert.

required
Array of DatapointsWithInternalId (object) or DatapointsWithExternalId (object) (DatapointsPostDatapoint) [ 1 .. 10000 ] items

Responses

Request samples

Content type
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{ }

List time series

List time series. Use nextCursor to paginate through the results.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Limits the number of results to return. CDF returns a maximum of 1000 results even if you specify a higher limit.

includeMetadata
boolean
Default: true

Whether the metadata field should be returned or not.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

partition
string
Example: partition=1/10

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.

assetIds
string <jsonArray(int64)> (JsonArrayInt64)
Example: assetIds=[363848954441724, 793045462540095, 1261042166839739]

Gets the time series related to the assets. The format is a list of IDs serialized as a JSON array(int64). Takes [ 1 .. 100 ] unique items.

rootAssetIds
string <jsonArray(int64)> (JsonArrayInt64)
Example: rootAssetIds=[363848954441724, 793045462540095, 1261042166839739]

Only includes time series that have a related asset in a tree rooted at any of these root assetIds.

externalIdPrefix
string (CogniteExternalIdPrefix) <= 255 characters
Example: externalIdPrefix=my.known.prefix

Filter by this (case-sensitive) prefix for the external ID.

Responses

Request samples

const timeseries = await client.timeseries.list({ filter: { assetIds: [1, 2] }});

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Retrieve data points

Retrieves a list of data points from multiple time series in a project. This operation supports aggregation and pagination. Learn more about aggregation.

Note: when start isn't specified in the top level and for an individual item, it will default to epoch 0, which is 1 January, 1970, thus excluding potential existent data points before 1970. start needs to be specified as a negative number to get data points before 1970.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Specify parameters to query for multiple data points. If you omit fields in individual data point query items, the top-level field values are used. For example, you can specify a default limit for all items by setting the top-level limit field. If you request aggregates, only the aggregates are returned. If you don't request any aggregates, all data points are returned.

required
Array of QueryWithInternalId (object) or QueryWithExternalId (object) (DatapointsQuery) [ 1 .. 100 ] items
integer or string (TimestampOrStringStart)

Get datapoints starting from, and including, this time. The format is N[timeunit]-ago where timeunit is w,d,h,m,s. Example: '2d-ago' gets datapoints that are up to 2 days old. You can also specify time in milliseconds since epoch. Note that for aggregates, the start time is rounded down to a whole granularity unit (in UTC timezone). Daily granularities (d) are rounded to 0:00 AM; hourly granularities (h) to the start of the hour, etc.

integer or string (TimestampOrStringEnd)

Get datapoints up to, but excluding, this point in time. Same format as for start. Note that when using aggregates, the end will be rounded up such that the last aggregate represents a full aggregation interval containing the original end, where the interval is the granularity unit times the granularity multiplier. For granularity 2d, the aggregation interval is 2 days, if end was originally 3 days after the start, it will be rounded to 4 days after the start.

limit
integer <int32>
Default: 100

Returns up to this number of data points. The maximum is 100000 non-aggregated data points and 10000 aggregated data points in total across all queries in a single request.

aggregates
Array of strings (Aggregate) [ 1 .. 10 ] items unique
Items Enum: "average" "max" "min" "count" "sum" "interpolation" "stepInterpolation" "totalVariation" "continuousVariance" "discreteVariance"

Specify the aggregates to return. Omit to return data points without aggregation.

granularity
string

The time granularity size and unit to aggregate over. Valid entries are 'day, hour, minute, second', or short forms 'd, h, m, s', or a multiple of these indicated by a number as a prefix. For 'second' and 'minute', the multiple must be an integer between 1 and 120 inclusive; for 'hour' and 'day', the multiple must be an integer between 1 and 100000 inclusive. For example, a granularity '5m' means that aggregates are calculated over 5 minutes. This field is required if aggregates are specified.

includeOutsidePoints
boolean
Default: false

Defines whether to include the last data point before the requested time period and the first one after. This option can be useful for interpolating data. It's not available for aggregates or cursors. Note: If there are more than limit data points in the time period, we will omit the excess data points and then append the first data point after the time period, thus causing a gap with omitted data points. When this is the case, we return up to limit+2 data points. When doing manual paging (sequentially requesting smaller intervals instead of requesting a larger interval and using cursors to get all the data points) with this field set to true, the start of the each subsequent request should be one millisecond more than the timestamp of the second-to-last data point from the previous response. This is because the last data point in most cases will be the extra point from outside the interval.

ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "start": 0,
  • "end": 0,
  • "limit": 100,
  • "aggregates": [
    • "average"
    ],
  • "granularity": "1h",
  • "includeOutsidePoints": false,
  • "ignoreUnknownIds": false
}

Response samples

Content type
{
  • "items": [
    • {
      }
    ]
}

Retrieve latest data point

Retrieves the latest data point in one or more time series. Note that the latest data point in a time series is the one with the highest timestamp, which is not necessarily the one that was ingested most recently.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

The list of the queries to perform.

required
Array of QueryWithInternalId (object) or QueryWithExternalId (object) (LatestDataBeforeRequest) [ 1 .. 100 ] items

List of latest queries

ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Retrieve time series

Retrieves one or more time series by ID or external ID. The response returns the time series in the same order as in the request.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of the IDs of the time series to retrieve.

required
Array of QueryWithInternalId (object) or QueryWithExternalId (object) [ 1 .. 1000 ] items unique

List of ID objects.

ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Search time series

Fulltext search for time series based on result relevance. Primarily meant for human-centric use cases, not for programs, since matching and order may change over time. Additional filters can also be specified. This operation does not support pagination.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
object (Filter)
object (Search)
limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Return up to this many results.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "name": "string",
    • "unit": "string",
    • "isString": true,
    • "isStep": true,
    • "metadata": {
      },
    • "assetIds": [
      ],
    • "assetExternalIds": [
      ],
    • "rootAssetIds": [
      ],
    • "assetSubtreeIds": [
      ],
    • "dataSetIds": [
      ],
    • "externalIdPrefix": "my.known.prefix",
    • "createdTime": {
      },
    • "lastUpdatedTime": {
      }
    },
  • "search": {
    • "name": "string",
    • "description": "string",
    • "query": "some other"
    },
  • "limit": 100
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Update time series

Updates one or more time series. Fields outside of the request remain unchanged.

For primitive fields (those whose type is string, number, or boolean), use "set": value to update the value; use "setNull": true to set the field to null.

For JSON array fields (for example securityCategories), use "set": [value1, value2] to update the value; use "add": [value1, value2] to add values; use "remove": [value1, value2] to remove values.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of changes.

required
Array of TimeSeriesUpdateById (object) or TimeSeriesUpdateByExternalId (object) (TimeSeriesUpdate) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Synthetic Time Series

Synthetic Time Series (STS) is a way to combine various input time series, constants and operators, to create completely new time series.

For example can we use the expression 24 * TS{externalId='production/hour'} to convert from hourly to daily production rates.

But STS is not limited to simple conversions.

  • We support combination of different time series TS{id=123} + TS{externalId='hei'}.
  • Functions of time series sin(pow(TS{id=123}, 2)).
  • Aggregations of time series TS{id=123, aggregate='average', granularity='1h'}+TS{id=456}

To learn more about synthetic time series please follow our guide.

Synthetic query

Execute an on-the-fly synthetic query

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

The list of queries to perform

required
Array of objects (SyntheticQuery) [ 1 .. 10 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Events

Event objects store complex information about multiple assets over a time period. For example, an event can describe two hours of maintenance on a water pump and some associated pipes, or a future time window where the pump is scheduled for inspection. This is in contrast with data points in time series that store single pieces of information about one asset at specific points in time (e.g., temperature measurements).

An event’s time period is defined by a start time and end time, both millisecond timestamps since the UNIX epoch. The timestamps can be in the future. In addition, events can have a text description as well as arbitrary metadata and properties.

Asset references obtained from an event - through asset ids - may be invalid, simply by the non-transactional nature of HTTP. They are maintained in an eventual consistent manner.

Rate and concurrency limits

Rate and concurrency limits apply to some of the endpoints. If a request exceeds one of the limits, it will be throttled with a 429: Too Many Requests response. More on limit types and how to avoid being throttled is described here.

Following limits apply to the List events, Filter events, Aggregate events and Search events endpoints. These limits apply to all endpoints simultaneously, i.e. requests made to different endpoints are counted together. Please note the additional conditions that apply to the Aggregate events endpoint, as this endpoint provides the most resource-consuming operations.

Limit Per project Per user (identity)
Rate 30 rps total
out of which no more than 15 rps to Aggregate
20 rps
out of which no more than 10 rps to Aggregate
Concurrency 15 parallel requests
out of which no more than 6 to Aggregate
10 parallel requests
out of which no more than 4 to Aggregate

Aggregate events

The aggregation API lets you compute aggregated results on events, such as getting the count of all Events in a project, checking different descriptions of events in your project, etc.

Aggregate filtering

Filter (filter & advancedFilter) data for aggregates

Filters behave the same way as for the Filter events endpoint. In text properties, the values are aggregated in a case-insensitive manner.

aggregateFilter to filter aggregate results

aggregateFilter works similarly to advancedFilter but always applies to aggregate properties. For instance, in an aggregation for the source property, only the values (aka buckets) of the source property can be filtered out.

Request throttling

This endpoint is meant for data analytics/exploration usage and is not suitable for high load data retrieval usage.
It is a subject of the new throttling schema (limited request rate and concurrency). Please check Events resource description for more information.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
One of
aggregate
string
Value: "count"

Type of aggregation to apply. count: Get an approximate number of Events matching the filters.

(BoolFilter (and (object) or or (object) or not (object))) or (LeafFilter (equals (object) or in (object) or range (object) or prefix (object) or exists (object) or containsAny (object) or containsAll (object) or search (object))) (EventAdvancedFilter)

A filter DSL (Domain Specific Language) to define advanced filter queries.

See more information about filtering DSL here.

Supported properties:

Property Type
["assetIds"] array of [number]
["createdTime"] number
["dataSetId"] number
["endTime"] number
["id"] number
["lastUpdatedTime"] number
["startTime"] number
["description"] string
["externalId"] string
["metadata"] string
["metadata", "someCustomKey"] string
["source"] string
["subtype"] string
["type"] string

Note: Filtering on the ["metadata"] property has the following logic: If a value of any metadata keys in an event matches the filter, the event matches the filter.

object (EventFilter)

Filter on events filter with exact match

Responses

Request samples

Content type
application/json
Example
{
  • "aggregate": "count",
  • "advancedFilter": {
    • "or": [
      ]
    },
  • "filter": {
    • "startTime": {
      },
    • "endTime": {
      },
    • "activeAtTime": {
      },
    • "metadata": {
      },
    • "assetIds": [
      ],
    • "assetExternalIds": [
      ],
    • "assetSubtreeIds": [
      ],
    • "dataSetId": {
      },
    • "dataSetIds": [
      ],
    • "source": "string",
    • "type": "string",
    • "subtype": "string",
    • "createdTime": {
      },
    • "lastUpdatedTime": {
      },
    • "externalIdPrefix": "my.known.prefix"
    }
}

Response samples

Content type
application/json
Example
{
  • "items": [
    • {
      }
    ]
}

Create events

Creates multiple event objects in the same project. It is possible to post a maximum of 1000 events per request.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of events to be posted. It is possible to post a maximum of 1000 events per request.

required
Array of objects (ExternalEvent) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete events

Deletes events with the given ids. A maximum of 1000 events can be deleted per request.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of IDs to delete.

required
Array of InternalId (object) or ExternalId (object) (EitherId) [ 1 .. 1000 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{ }

Filter events

Retrieve a list of events in the same project. This operation supports pagination by cursor. Apply Filtering and Advanced filtering criteria to select a subset of events.

Advanced filtering

Advanced filter lets you create complex filtering expressions that combine simple operations, such as equals, prefix, exists, etc., using boolean operators and, or, and not. It applies to basic fields as well as metadata.

See the advancedFilter attribute in the example.

See more information about filtering DSL here.

Supported leaf filters

Leaf filter Supported fields Description
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 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 value.
{"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 ["description"] Introduced to provide functional parity with /events/search endpoint.
{"search": {"property": ["property"], "value": "example"}}

The search leaf filter provides functional parity with the /events/search endpoint. It's available only for the ["description"] field. When specifying only this filter with no explicit ordering, behavior is the same as of the /events/search/ endpoint without specifying filters. Explicit sorting overrides the default ordering by relevance. It's possible to use the search leaf filter as any other leaf filter for creating complex queries.

See the search filter in the advancedFilter attribute in the example.

advancedFilter attribute limits

  • filter query max depth: 10
  • filter query max number of clauses: 100
  • and and or clauses must have at least one element
  • property array of each leaf filter has the following limitations:
    • number of elements in the array is in the range [1, 2]
    • elements must not be blank
    • each element max length is 128 symbols
    • property array must match one of the existing properties (static or dynamic metadata)
  • 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 a primitive type (number, string)
  • range filter must have at least one of gt, gte, lt, lte attributes. But gt is mutually exclusive to gte, while lt is mutually exclusive to lte. For metadata, both upper and lower bounds must be specified.
  • gt, gte, lt, lte in the range filter must be a primitive value
  • search filter value must not be blank and the length must be in the range [1, 128]
  • filter query may have maximum 2 search leaf filters
  • maximum leaf filter string value length is different depending on the property the filter is using:
    • externalId - 255
    • description - 128 for the search filter and 255 for other filters
    • type - 64
    • subtype - 64
    • source - 128
    • any metadata key - 128

Sorting

By default, events are sorted by their creation time in the ascending order. Use the search leaf filter to sort the results by relevance. Sorting by other fields can be explicitly requested. The order field is optional and defaults to desc for _score_ and asc for all other fields. The nulls field is optional and defaults to auto. auto is translated to last for the asc order and to first for the desc order by the service. Partitions are done independently of sorting: there's no guarantee of the sort order between elements from different partitions.

See the sort attribute in the example.

Null values

In case the nulls attribute has the auto value or the attribute isn't specified, null (missing) values are considered to be bigger than any other values. They are placed last when sorting in the asc order and first when sorting in desc. Otherwise, missing values are placed according to the nulls attribute (last or first), and their placement doesn't depend on the order value. Values, such as empty strings, aren't considered as nulls.

Sorting by score

Use a special sort property _score_ when sorting by relevance. The more filters a particular event matches, the higher its score is. This can be useful, for example, when building UIs. Let's assume we want exact matches to be be displayed above matches by prefix as in the request below. An event with the type fire will match both equals and prefix filters and, therefore, have higher score than events with names like fire training that match only the prefix filter.

"advancedFilter" : {
  "or" : [
    {
      "equals": {
        "property": ["type"], 
        "value": "fire"
      }
    },
    {
      "prefix": {
        "property": ["type"], 
        "value": "fire"
      }
    }
  ]
},
"sort": [
  {
    "property" : ["_score_"]
  }
]

Request throttling

This endpoint is meant for data analytics/exploration usage and is not suitable for high load data retrieval usage. It is a subject of the new throttling schema (limited request rate and concurrency). Please check Events resource description for more information.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
object (EventFilter)

Filter on events filter with exact match

(BoolFilter (and (object) or or (object) or not (object))) or (LeafFilter (equals (object) or in (object) or range (object) or prefix (object) or exists (object) or containsAny (object) or containsAll (object) or search (object))) (EventAdvancedFilter)

A filter DSL (Domain Specific Language) to define advanced filter queries.

See more information about filtering DSL here.

Supported properties:

Property Type
["assetIds"] array of [number]
["createdTime"] number
["dataSetId"] number
["endTime"] number
["id"] number
["lastUpdatedTime"] number
["startTime"] number
["description"] string
["externalId"] string
["metadata"] string
["metadata", "someCustomKey"] string
["source"] string
["subtype"] string
["type"] string

Note: Filtering on the ["metadata"] property has the following logic: If a value of any metadata keys in an event matches the filter, the event matches the filter.

limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Limits the maximum number of results to be returned by a single request. In case there are more results to the request, the 'nextCursor' attribute will be provided as part of the response. Request may contain less results than the request limit.

Array of objects (modern) <= 2 items

Sort by array of selected properties.

cursor
string
partition
string (Partition)

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.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "startTime": {
      },
    • "endTime": {
      },
    • "activeAtTime": {
      },
    • "metadata": {
      },
    • "assetIds": [
      ],
    • "assetExternalIds": [
      ],
    • "assetSubtreeIds": [
      ],
    • "dataSetId": {
      },
    • "dataSetIds": [
      ],
    • "source": "string",
    • "type": "string",
    • "subtype": "string",
    • "createdTime": {
      },
    • "lastUpdatedTime": {
      },
    • "externalIdPrefix": "my.known.prefix"
    },
  • "advancedFilter": {
    • "or": [
      ]
    },
  • "limit": 100,
  • "sort": [
    • {
      },
    • {
      }
    ],
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
  • "partition": "1/10"
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

List events

List events optionally filtered on query parameters

Request throttling

This endpoint is meant for data analytics/exploration usage and is not suitable for high load data retrieval usage. It is a subject of the new throttling schema (limited request rate and concurrency). Please check Events resource description for more information.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

minStartTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

maxStartTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

minEndTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

maxEndTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

minActiveAtTime
integer <int64> >= 0

Event is considered active from its startTime to endTime inclusive. If startTime is null, event is never active. If endTime is null, event is active from startTime onwards. activeAtTime filter will match all events that are active at some point from min to max, from min, or to max, depending on which of min and max parameters are specified.

maxActiveAtTime
integer <int64> >= 0

Event is considered active from its startTime to endTime inclusive. If startTime is null, event is never active. If endTime is null, event is active from startTime onwards. activeAtTime filter will match all events that are active at some point from min to max, from min, or to max, depending on which of min and max parameters are specified.

assetIds
string <jsonArray(int64)> (JsonArrayInt64)
Example: assetIds=[363848954441724, 793045462540095, 1261042166839739]

Asset IDs of equipment that this event relates to. Format is list of IDs serialized as JSON array(int64). Takes [ 1 .. 100 ] of unique items.

assetExternalIds
string <jsonArray(string)> (JsonArrayString)
Example: assetExternalIds=["externalId1", "externalId2", "externalId3"]

Asset external IDs of equipment that this event relates to. Takes 1..100 unique items.

assetSubtreeIds
string <jsonArray(int64)> (JsonArrayInt64)
Example: assetSubtreeIds=[363848954441724, 793045462540095, 1261042166839739]

Only include events that have a related asset in a subtree rooted at any of these assetIds (including the roots given). If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.

assetSubtreeExternalIds
string <jsonArray(string)> (JsonArrayString)
Example: assetSubtreeExternalIds=["externalId1", "externalId2", "externalId3"]

Only include events that have a related asset in a subtree rooted at any of these assetExternalIds (including the roots given). If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.

source
string <= 128 characters

The source of this event.

type
string (EventType) <= 64 characters

Type of the event, e.g 'failure'.

subtype
string (EventSubType) <= 64 characters

SubType of the event, e.g 'electrical'.

minCreatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

maxCreatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

minLastUpdatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

maxLastUpdatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

externalIdPrefix
string (CogniteExternalIdPrefix) <= 255 characters
Example: externalIdPrefix=my.known.prefix

Filter by this (case-sensitive) prefix for the external ID.

partition
string
Example: partition=1/10

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.

includeMetadata
boolean
Default: true

Whether the metadata field should be returned or not.

sort
Array of strings
Example: sort=endTime:desc

Sort by an array of the selected fields. Syntax: ["<fieldname>:asc|desc"]. Default sort order is asc with short syntax: ["<fieldname>"]. Filter accepts the following field names: dataSetId, externalId, type, subtype, startTime, endTime, createdTime, lastUpdatedTime, source, description, metadata. Partitions are done independently of sorting, there's no guarantee on sort order between elements from different partitions.

Responses

Request samples

const events = await client.events.list({ filter: { startTime: { min: new Date('1 jan 2018') }, endTime: { max: new Date('1 jan 2019') } } });

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Receive an event by its ID

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
id
required
integer <int64> (CogniteInternalId) [ 1 .. 9007199254740991 ]

A server-generated ID for the object.

Responses

Request samples

const events = await client.events.retrieve([{id: 123}, {externalId: 'abc'}]);

Response samples

Content type
application/json
{
  • "externalId": "my.known.id",
  • "dataSetId": 1,
  • "startTime": 0,
  • "endTime": 0,
  • "type": "string",
  • "subtype": "string",
  • "description": "string",
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    },
  • "assetIds": [
    • 1
    ],
  • "source": "string",
  • "id": 1,
  • "lastUpdatedTime": 0,
  • "createdTime": 0
}

Retrieve events

Retrieves information about events in the same project. Events are returned in the same order as the ids listed in the query.

A maximum of 1000 event IDs may be listed per request and all of them must be unique.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of IDs of events to retrieve. Must be up to a maximum of 1000 IDs, and all of them must be unique.

required
Array of InternalId (object) or ExternalId (object) (EitherId) [ 1 .. 1000 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Search events

Fulltext search for events based on result relevance. Primarily meant for human-centric use-cases, not for programs, since matching and ordering may change over time. Additional filters can also be specified. This operation doesn't support pagination.

Request throttling

This endpoint is meant for data analytics/exploration usage and is not suitable for high load data retrieval usage. It is a subject of the new throttling schema (limited request rate and concurrency). Please check Events resource description for more information.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
object (EventFilter)

Filter on events filter with exact match

object (EventSearch)
limit
integer <int32> [ 1 .. 1000 ]
Default: 100

<- Limits the maximum number of results to be returned by single request. Request may contain less results than request limit.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "startTime": {
      },
    • "endTime": {
      },
    • "activeAtTime": {
      },
    • "metadata": {
      },
    • "assetIds": [
      ],
    • "assetExternalIds": [
      ],
    • "assetSubtreeIds": [
      ],
    • "dataSetId": {
      },
    • "dataSetIds": [
      ],
    • "source": "string",
    • "type": "string",
    • "subtype": "string",
    • "createdTime": {
      },
    • "lastUpdatedTime": {
      },
    • "externalIdPrefix": "my.known.prefix"
    },
  • "search": {
    • "description": "string"
    },
  • "limit": 100
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Update events

Updates events in the same project. This operation supports partial updates; Fields omitted from queries will remain unchanged on objects.

For primitive fields (String, Long, Int), use 'set': 'value' to update value; use 'setNull': true to set that field to null.

For the Json Array field (e.g. assetIds), use 'set': [value1, value2] to update value; use 'add': [v1, v2] to add values to current list of values; use 'remove': [v1, v2] to remove these values from current list of values if exists.

A maximum of 1000 events can be updated per request, and all of the event IDs must be unique.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of changes. A maximum of 1000 events can be updated per request, and all of the event IDs must be unique.

required
Array of EventChangeById (object) or EventChangeByExternalId (object) (EventChange) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Files

A file stores a sequence of bytes connected to one or more assets. For example, a file can contain a piping and instrumentation diagram (P&IDs) showing how multiple assets are connected.

Each file is identified by the 'id' field, which is generated internally for each new file. Each file's 'id' field is unique within a project.

The 'externalId' field is optional, but can also be used to identify a file. The 'externalId' (if used) must be unique within a project.

Files are created in two steps; First the metadata is stored in a file object, and then the file contents are uploaded. This means that files can exist in a non-uploaded state. The upload state is reflected in the 'uploaded' field in responses.

Asset references obtained from a file - through asset ids - may be invalid, simply by the non-transactional nature of HTTP. They are maintained in an eventual consistent manner.

Aggregate files

Calculate aggregates for files, based on optional filter specification. Returns the following aggregates: count

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Files aggregate request body

object

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "name": "string",
    • "directoryPrefix": "/my/known/directory",
    • "mimeType": "image/jpeg",
    • "metadata": {
      },
    • "assetIds": [
      ],
    • "assetExternalIds": [
      ],
    • "rootAssetIds": [
      ],
    • "dataSetIds": [
      ],
    • "assetSubtreeIds": [
      ],
    • "source": "string",
    • "createdTime": {
      },
    • "lastUpdatedTime": {
      },
    • "uploadedTime": {
      },
    • "sourceCreatedTime": {
      },
    • "sourceModifiedTime": {
      },
    • "externalIdPrefix": "my.known.prefix",
    • "uploaded": true,
    • "labels": {
      },
    • "geoLocation": {
      }
    }
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Complete multipart upload

Completes a multipart file upload. This endpoint must be called by the client when an 'initMultiPartUpload' operation (POST /files/initmultipartupload) was called, and all file content parts have been successfully uploaded using PUT for all upload URLs. Either id or externalId must be specified in the request body, but not both. The uploadId is also required. The values for these properties can be retrieved from the response of the initMultiPartUpload operation.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

The JSON request body which specifies which file id/externalId and uploadId to complete the multipart upload for.

One of
id
integer <int64> (CogniteInternalId) [ 1 .. 9007199254740991 ]

A server-generated ID for the object.

uploadId
required
string

A server-generated identifier returned by 'files/initmultipartupload', used by 'files/completemultipartupload' for validation purposes.

Responses

Request samples

Content type
application/json
Example
{
  • "id": 1,
  • "uploadId": "string"
}

Response samples

Content type
application/json
{ }

Delete files

Deletes the files with the given ids.

A maximum of 1000 files can be deleted per request.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of IDs of files to delete.

Array of FileInternalId (object) or FileExternalId (object) (FileIdEither) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{ }

Filter files

Retrieves a list of all files in a project. Criteria can be supplied to select a subset of files. This operation supports pagination with cursors.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

The project name

object
partition
string (Partition)

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.

limit
integer <int32> [ 1 .. 1000 ]
Default: 100

<- Maximum number of items that the client want to get back.

cursor
string

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "name": "string",
    • "directoryPrefix": "/my/known/directory",
    • "mimeType": "image/jpeg",
    • "metadata": {
      },
    • "assetIds": [
      ],
    • "assetExternalIds": [
      ],
    • "rootAssetIds": [
      ],
    • "dataSetIds": [
      ],
    • "assetSubtreeIds": [
      ],
    • "source": "string",
    • "createdTime": {
      },
    • "lastUpdatedTime": {
      },
    • "uploadedTime": {
      },
    • "sourceCreatedTime": {
      },
    • "sourceModifiedTime": {
      },
    • "externalIdPrefix": "my.known.prefix",
    • "uploaded": true,
    • "labels": {
      },
    • "geoLocation": {
      }
    },
  • "partition": "1/10",
  • "limit": 100,
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo"
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Get icon

The GET /files/icon operation can be used to get an image representation of a file.

Either id or externalId must be provided as a query parameter (but not both). Supported file formats:

  • Normal jpeg and png files are currently fully supported.
  • Other image file formats might work, but continued support for these are not guaranteed.
  • Currently only supporting thumbnails for image files. Attempts to get icon for unsupported files will result in status 400.
Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
id
integer <int64> (CogniteInternalId) [ 1 .. 9007199254740991 ]

A server-generated ID for the object.

externalId
string (CogniteExternalId) <= 255 characters
Example: externalId=my.known.id

The external ID provided by the client. Must be unique for the resource type.

Responses

Response samples

Content type
application/json
{
  • "error": {
    • "code": 401,
    • "message": "Could not authenticate.",
    • "missing": [
      ],
    • "duplicated": [
      ]
    }
}

List files

The GET /files operation can be used to return information for all files in a project.

Optionally you can add one or more of the following query parameters. The filter query parameters will filter the results to only include files that match all filter parameters.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

name
string (FileName) <= 256 characters

Name of the file.

mimeType
string (MimeType) <= 256 characters
Example: mimeType=image/jpeg

File type. E.g. text/plain, application/pdf, ..

source
string (FileSource) <= 128 characters

The source of the file.

assetIds
Array of integers <int64> (AssetIds) [ 1 .. 100 ] items unique [ items <int64 > [ 1 .. 9007199254740991 ] ]
Example: assetIds=363848954441724&assetIds=793045462540095&assetIds=1261042166839739

Only include files that reference these specific asset IDs.

assetExternalIds
string <jsonArray(string)> (JsonArrayString)
Example: assetExternalIds=["externalId1", "externalId2", "externalId3"]

Asset external IDs of related equipment that this file relates to. Takes 1..100 unique items.

Array of DataSetInternalId (object) or DataSetExternalId (object) (DataSetIdEithers)
rootAssetIds
string <jsonArray(int64)> (JsonArrayInt64)
Example: rootAssetIds=[363848954441724, 793045462540095, 1261042166839739]

Only include files that have a related asset in a tree rooted at any of these root assetIds.

assetSubtreeIds
string <jsonArray(int64)> (JsonArrayInt64)
Example: assetSubtreeIds=[363848954441724, 793045462540095, 1261042166839739]

Only include files that have a related asset in a subtree rooted at any of these assetIds (including the roots given). If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.

assetSubtreeExternalIds
string <jsonArray(string)> (JsonArrayString)
Example: assetSubtreeExternalIds=["externalId1", "externalId2", "externalId3"]

Only include files that have a related asset in a subtree rooted at any of these assetExternalIds (including the roots given). If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.

minCreatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

maxCreatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

minLastUpdatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

maxLastUpdatedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

minUploadedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

maxUploadedTime
integer <int64> (EpochTimestamp) >= 0

The number of milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

minSourceCreatedTime
integer <int64> (EpochTimestamp) >= 0

Include files that have sourceCreatedTime set and with minimum this value.

maxSourceCreatedTime
integer <int64> (EpochTimestamp) >= 0

Include files that have sourceCreatedTime set and with maximum this value.

minSourceModifiedTime
integer <int64> (EpochTimestamp) >= 0

Include files that have sourceModifiedTime set and with minimum this value.

maxSourceModifiedTime
integer <int64> (EpochTimestamp) >= 0

Include files that have sourceModifiedTime set and with maximum this value.

externalIdPrefix
string (CogniteExternalIdPrefix) <= 255 characters
Example: externalIdPrefix=my.known.prefix

Filter by this (case-sensitive) prefix for the external ID.

uploaded
boolean
Example: uploaded=true

Whether or not the actual file is uploaded. This field is returned only by the API, it has no effect in a post body.

partition
string
Example: partition=1/10

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.

Responses

Request samples

const files = await client.files.list({filter: {mimeType: 'image/png'}});

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Retrieve a file by its ID

Returns file info for the file ID

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
id
required
integer <int64> (CogniteInternalId) [ 1 .. 9007199254740991 ]

A server-generated ID for the object.

Responses

Request samples

const files = await client.files.retrieve([{id: 123}, {externalId: 'abc'}]);

Response samples

Content type
application/json
{
  • "externalId": "my.known.id",
  • "name": "string",
  • "directory": "string",
  • "source": "string",
  • "mimeType": "image/jpeg",
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    },
  • "assetIds": [
    • 1
    ],
  • "dataSetId": 1,
  • "sourceCreatedTime": 0,
  • "sourceModifiedTime": 0,
  • "securityCategories": [
    • 1
    ],
  • "labels": [
    • {
      }
    ],
  • "geoLocation": {
    • "type": "Feature",
    • "geometry": {
      },
    • "properties": { }
    },
  • "id": 1,
  • "uploaded": true,
  • "uploadedTime": 0,
  • "createdTime": 0,
  • "lastUpdatedTime": 0
}

Retrieve files

Retrieves metadata information about multiple specific files in the same project. Results are returned in the same order as in the request. This operation does not return the file contents.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of IDs of files to retrieve. Must be up to a maximum of 1000 IDs, and all of them must be unique.

required
Array of Select by Id (object) or Select by ExternalId (object) (FileSelectEither) [ 1 .. 1000 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Search files

Search for files based on relevance. You can also supply a strict match filter as in Filter files, and search in the results from the filter. Returns first 1000 results based on relevance. This operation does not support pagination.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
object
object

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "name": "string",
    • "directoryPrefix": "/my/known/directory",
    • "mimeType": "image/jpeg",
    • "metadata": {
      },
    • "assetIds": [
      ],
    • "assetExternalIds": [
      ],
    • "rootAssetIds": [
      ],
    • "dataSetIds": [
      ],
    • "assetSubtreeIds": [
      ],
    • "source": "string",
    • "createdTime": {
      },
    • "lastUpdatedTime": {
      },
    • "uploadedTime": {
      },
    • "sourceCreatedTime": {
      },
    • "sourceModifiedTime": {
      },
    • "externalIdPrefix": "my.known.prefix",
    • "uploaded": true,
    • "labels": {
      },
    • "geoLocation": {
      }
    },
  • "search": {
    • "name": "string"
    }
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Update files

Updates the information for the files specified in the request body.

If you want to update the file content, uploaded using the uploadUrl, please use the initFileUpload request with the query parameter 'overwrite=true'. Alternatively, delete and recreate the file.

For primitive fields (String, Long, Int), use 'set': 'value' to update value; use 'setNull': true to set that field to null.

For the Json Array field (e.g. assetIds and securityCategories): Use either only 'set', or a combination of 'add' and/or 'remove'.

AssetIds update examples:

Example request body to overwrite assetIds with a new set, asset ID 1 and 2.

{
  "items": [
    {
      "id": 1,
      "update": {
        "assetIds" : {
          "set" : [ 1, 2 ]
        }
      }
    }
  ]
}

Example request body to add one asset Id, and remove another asset ID.

{
  "items": [
    {
      "id": 1,
      "update": {
        "assetIds" : {
          "add" : [ 3 ],
          "remove": [ 2 ]
        }
      }
    }
  ]
}

Metadata update examples:

Example request body to overwrite metadata with a new set.

{
  "items": [
    {
      "id": 1,
      "update": {
        "metadata": {
          "set": {
            "key1": "value1",
            "key2": "value2"
          }
        }
      }
    }
  ]
}

Example request body to add two key-value pairs and remove two other key-value pairs by key for the metadata field.

{
  "items": [
    {
      "id": 1,
      "update": {
        "metadata": {
          "add": {
            "key3": "value3",
            "key4": "value4"
          },
          "remove": [
            "key1",
            "key2"
          ]
        }
      }
    }
  ]
}
Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

The JSON request body which specifies which files and fields to update.

required
Array of FileChangeUpdateById (object) or FileChangeUpdateByExternalId (object) (FileChangeUpdate) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Upload file

Create metadata information and get an uploadUrl for a file.

To upload the file, send an HTTP PUT request to the uploadUrl from the response, with the relevant 'Content-Type' and 'Content-Length' headers.

If the uploadUrl contains the string '/v1/files/gcs_proxy/', you can make a Google Cloud Storage (GCS) resumable upload request as documented in https://cloud.google.com/storage/docs/json_api/v1/how-tos/resumable-upload.

The uploadUrl expires after one week. Any file info entry that does not have the actual file uploaded within one week will be automatically deleted.

Note: The uploadUrl from initFileUpload supports files smaller than 5 GiB.

The initMultiPartUpload and completeMultiPartUpload endpoints provides an alternative way to upload files, both small and large, up to 1 TiB in size. These endpoints exposes a uniform multipart upload API for all cloud vendor environments for CDF. Optionally parallel part uploads can be used, for faster uploads.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
overwrite
boolean
Default: false

If 'overwrite' is set to true, and the POST body content specifies a 'externalId' field, fields for the file found for externalId can be overwritten. The default setting is false.

If metadata is included in the request body, all of the original metadata will be overwritten. The actual file will be overwritten after a successful upload with the uploadUrl from the response. If there is no successful upload, the current file contents will be kept.

File-Asset mappings only change if explicitly stated in the assetIds field of the POST json body. Do not set assetIds in request body if you want to keep the current file-asset mappings.

header Parameters
Origin
string

The 'Origin' header parameter is required if there is a Cross Origin issue.

Request Body schema: application/json

Fields to be set for the file.

externalId
string (CogniteExternalId) <= 255 characters

The external ID provided by the client. Must be unique for the resource type.

name
required
string (FileName) <= 256 characters

Name of the file.

directory
string (FileDirectory) <= 512 characters

Directory containing the file. Must be an absolute, unix-style path.

source
string (FileSource) <= 128 characters

The source of the file.

mimeType
string (MimeType) <= 256 characters

File type. E.g. text/plain, application/pdf, ..

object (FilesMetadataField)

Custom, application specific metadata. String key -> String value. Limits: Maximum length of key is 128 bytes, value 10240 bytes, up to 256 key-value pairs, of total size at most 10240.

assetIds
Array of integers <int64> (CogniteInternalId) [ 1 .. 1000 ] items [ items <int64 > [ 1 .. 9007199254740991 ] ]
dataSetId
integer <int64> (DataSetId) [ 1 .. 9007199254740991 ]

The dataSet Id for the item.

sourceCreatedTime
integer <int64> >= 0

The timestamp for when the file was originally created in the source system.

sourceModifiedTime
integer <int64> >= 0

The timestamp for when the file was last modified in the source system.

securityCategories
Array of integers <int64> (CogniteInternalId) [ 0 .. 100 ] items [ items <int64 > [ 1 .. 9007199254740991 ] ]

The security category IDs required to access this file.

Array of objects (LabelList) [ 0 .. 10 ] items unique

A list of the labels associated with this resource item.

object (GeoLocation)

Geographic metadata.

Responses

Request samples

Content type
application/json
{
  • "externalId": "my.known.id",
  • "name": "string",
  • "directory": "string",
  • "source": "string",
  • "mimeType": "image/jpeg",
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    },
  • "assetIds": [
    • 1
    ],
  • "dataSetId": 1,
  • "sourceCreatedTime": 0,
  • "sourceModifiedTime": 0,
  • "securityCategories": [
    • 1
    ],
  • "labels": [
    • {
      }
    ],
  • "geoLocation": {
    • "type": "Feature",
    • "geometry": {
      },
    • "properties": { }
    }
}

Response samples

Content type
application/json
{
  • "externalId": "my.known.id",
  • "name": "string",
  • "directory": "string",
  • "source": "string",
  • "mimeType": "image/jpeg",
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    },
  • "assetIds": [
    • 1
    ],
  • "dataSetId": 1,
  • "sourceCreatedTime": 0,
  • "sourceModifiedTime": 0,
  • "securityCategories": [
    • 1
    ],
  • "labels": [
    • {
      }
    ],
  • "geoLocation": {
    • "type": "Feature",
    • "geometry": {
      },
    • "properties": { }
    },
  • "id": 1,
  • "uploaded": true,
  • "uploadedTime": 0,
  • "createdTime": 0,
  • "lastUpdatedTime": 0,
  • "uploadUrl": "string"
}

Upload multipart file

Multipart file upload enables upload of files larger than 5 GiB, using a uniform API on all cloud environments for CDF.

Each file part must be larger than 5 MiB, and smaller than 5 GiB. The file part for the last uploadURL can be smaller than 5 MiB. The client should calculate the ideal number of parts depending on predetermined or estimated file size, between 1 and the maximum. Specify the number of parts in the parts URL query parameter. The parts parameter is required.

The request creates metadata information for a new file, and returns in addition to the file id, also a uploadId, and a list of uploadUrls for uploading the file contents. To upload a file, send an HTTP PUT request to each of the uploadUrls, with the corresponding part of the file in the request body. You may use a 'Content-Length' header in the PUT request for each part, but this is not required. A failed part PUT upload can be retried.

The client must ensure that the parts of the source file are stored in the correct order, using the order of the uploadUrls as specified in the response. This to avoid ending up with a corrupt final file.

The parts can optionally be uploaded in parallel, preferably on a subset of parts at a time, for example maximum 3 concurrent PUT operations.

Once all file parts have been uploaded, the client should call the 'files/completemultipartupload' endpoint, with the required file ID (as id or externalId) and uploadId fields in the request body. This will assemble the parts into one file. The file's uploaded flag will then eventually be set to true.

A standard sequence of calls to upload a large file with multipart upload would be for example as follows:

  1. POST files/initmultipartupload?parts=8, to start a multipart upload session with 8 parts. Expect a 201 CREATED response code, and a response body with information to be used in the part uploads and completemultipartupload requests.
  2. PUT uploadUrl, for each of the uploadUrls in the response from files/initmultipartupload. Expect a 200 OK or 201 CREATED response for each PUT request.
  3. POST files/completemultipartupload, with request body '{ "id":123456789, "uploadId":"ABCD4321EFGH" }'. This will assemble the file. Expect a 200 OK response.

Consider verifying that the file is eventually marked as uploaded with a call to the getFileByInternalId endpoint.

NOTE: The uploadUrls expires after one week. A file that does not have the file content parts uploaded and completed within one week will be automatically deleted.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
overwrite
boolean
Default: false

If 'overwrite' is set to true, and the POST body content specifies a 'externalId' field, fields for the file found for externalId can be overwritten. The default setting is false.

If metadata is included in the request body, all of the original metadata will be overwritten. The actual file will be overwritten after a successful upload with the uploadUrls from the response. If there is no successful upload, the current file contents will be kept.

File-Asset mappings only change if explicitly stated in the assetIds field of the POST json body. Do not set assetIds in request body if you want to keep the current file-asset mappings.

parts
required
integer <int32> [ 1 .. 200 ]

The 'parts' parameter specifies how many uploadURLs should be returned, for uploading the file contents in parts. See main endpoint description for more details.

Request Body schema: application/json

Fields to be set for the file.

externalId
string (CogniteExternalId) <= 255 characters

The external ID provided by the client. Must be unique for the resource type.

name
required
string (FileName) <= 256 characters

Name of the file.

directory
string (FileDirectory) <= 512 characters

Directory containing the file. Must be an absolute, unix-style path.

source
string (FileSource) <= 128 characters

The source of the file.

mimeType
string (MimeType) <= 256 characters

File type. E.g. text/plain, application/pdf, ..

object (FilesMetadataField)

Custom, application specific metadata. String key -> String value. Limits: Maximum length of key is 128 bytes, value 10240 bytes, up to 256 key-value pairs, of total size at most 10240.

assetIds
Array of integers <int64> (CogniteInternalId) [ 1 .. 1000 ] items [ items <int64 > [ 1 .. 9007199254740991 ] ]
dataSetId
integer <int64> (DataSetId) [ 1 .. 9007199254740991 ]

The dataSet Id for the item.

sourceCreatedTime
integer <int64> >= 0

The timestamp for when the file was originally created in the source system.

sourceModifiedTime
integer <int64> >= 0

The timestamp for when the file was last modified in the source system.

securityCategories
Array of integers <int64> (CogniteInternalId) [ 0 .. 100 ] items [ items <int64 > [ 1 .. 9007199254740991 ] ]

The security category IDs required to access this file.

Array of objects (LabelList) [ 0 .. 10 ] items unique

A list of the labels associated with this resource item.

object (GeoLocation)

Geographic metadata.

Responses

Request samples

Content type
application/json
{
  • "externalId": "my.known.id",
  • "name": "string",
  • "directory": "string",
  • "source": "string",
  • "mimeType": "image/jpeg",
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    },
  • "assetIds": [
    • 1
    ],
  • "dataSetId": 1,
  • "sourceCreatedTime": 0,
  • "sourceModifiedTime": 0,
  • "securityCategories": [
    • 1
    ],
  • "labels": [
    • {
      }
    ],
  • "geoLocation": {
    • "type": "Feature",
    • "geometry": {
      },
    • "properties": { }
    }
}

Response samples

Content type
application/json
{
  • "externalId": "my.known.id",
  • "name": "string",
  • "directory": "string",
  • "source": "string",
  • "mimeType": "image/jpeg",
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    },
  • "assetIds": [
    • 1
    ],
  • "dataSetId": 1,
  • "sourceCreatedTime": 0,
  • "sourceModifiedTime": 0,
  • "securityCategories": [
    • 1
    ],
  • "labels": [
    • {
      }
    ],
  • "geoLocation": {
    • "type": "Feature",
    • "geometry": {
      },
    • "properties": { }
    },
  • "id": 1,
  • "uploaded": true,
  • "uploadedTime": 0,
  • "createdTime": 0,
  • "lastUpdatedTime": 0,
  • "uploadId": "string",
  • "uploadUrls": [
    • "uploadURL_for_part_1",
    • "uploadURL_for_part_2",
    • "uploadURL_for_part_3"
    ]
}

Sequences

A sequence stores a table with up to 400 columns indexed by row number. There can be at most 400 numeric columns and 200 string columns. Each of the columns has a pre-defined type: a string, integer, or floating point number.

For example, a sequence can represent a curve, either with the dependent variable x as the row number and a single value column y, or can simply store (x,y) pairs in the rows directly. Other potential applications include data logs in which the index isn't time-based. To learn more about sequences, see the concept guide.

Aggregate sequences

The aggregation API allows you to compute aggregated results from a set of sequences, such as getting the number of sequences in a project or checking what assets the different sequences in your project are associated with (along with the number of sequences for each asset). By specifying filter and/or advancedFilter, the aggregation will take place only over those sequences that match the filters. filter and advancedFilter behave the same way as in the list endpoint.

The default behavior, when the aggregate field is not specified the request body, is to return the number of sequences that match the filters (if any), which is the same behavior as when the aggregate field is set to count.

The following requests will both return the total number of sequences whose name begins with pump:

{
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}}
}

and

{
  "aggregate": "count",
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}}
}

The response might be:

{"items": [{"count": 42}]}
Setting aggregate to uniqueValues and specifying a property in properties (this field is an array, but currently only supports one property) will return all unique values (up to a maximum of 1000) that are taken on by that property across all the sequences that match the filters, as well as the number of sequences that have each of those property values.

This example request finds all the unique asset ids that are referenced by the sequences in your project whose name begins with pump:

{
  "aggregate": "uniqueValues",
  "properties": [{"property": ["assetId"]}],
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}}
}

The response might be the following, saying that 23 sequences are associated with asset 18 and 107 sequences are associated with asset 76:

{
  "items": [
    {"values": ["18"], "count": 23},
    {"values": ["76"], "count": 107}
  ]
}
Setting aggregate to cardinalityValues will instead return the approximate number of distinct values that are taken on by the given property among the matching sequences.

Example request:

{
  "aggregate": "cardinalityValues",
  "properties": [{"property": ["assetId"]}],
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}}
}

The result is likely exact when the set of unique values is small. In this example, there are likely two distinct asset ids among the matching sequences:

{"items": [{"count": 2}]}
Setting aggregate to uniqueProperties will return the set of unique properties whose property path begins with path (which can currently only be ["metadata"]) that are contained in the sequences that match the filters.

Example request:

{
  "aggregate": "uniqueProperties",
  "path": ["metadata"],
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}}
}

The result contains all the unique metadata keys in the sequences whose name begins with pump, and the number of sequences that contains each metadata key:

{
  "items": [
    {"values": [{"property": ["metadata", "tag"]}], "count": 43},
    {"values": [{"property": ["metadata", "installationDate"]}], "count": 97}
  ]
}
Setting aggregate to cardinalityProperties will instead return the approximate number of different property keys whose path begins with path (which can currently only be ["metadata"], meaning that this can only be used to count the approximate number of distinct metadata keys among the matching sequences).

Example request:

{
  "aggregate": "cardinalityProperties",
  "path": ["metadata"],
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}}
}

The result is likely exact when the set of unique values is small. In this example, there are likely two distinct metadata keys among the matching sequences:

{"items": [{"count": 2}]}

The aggregateFilter field may be specified if aggregate is set to cardinalityProperties or uniqueProperties. The structure of this field is similar to that of advancedFilter, except that the set of leaf filters is smaller (in, prefix, and range), and that none of the leaf filters specify a property. Unlike advancedFilter, which is applied before the aggregation (in order to restrict the set of sequences that the aggregation operation should be applied to), aggregateFilter is applied after the initial aggregation has been performed, in order to restrict the set of results.

Click here for more details about aggregateFilter.

When aggregate is set to uniqueProperties, the result set contains a number of property paths, each with an associated count that shows how many sequences contained that property (among those sequences that matched the filter and advancedFilter, if they were specified) . If aggregateFilter is specified, it will restrict the property paths included in the output. Let us add an aggregateFilter to the uniqueProperties example from above:

{
  "aggregate": "uniqueProperties",
  "path": ["metadata"],
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}},
  "aggregateFilter": {"prefix": {"value": "t"}}
}

Now, the result only contains those metadata properties whose key begins with t (but it will be the same set of metadata properties that begin with t as in the original query without aggregateFilter, and the counts will be the same):

{
  "items": [
    {"values": [{"property": ["metadata", "tag"]}], "count": 43}
  ]
}

Similarly, adding aggregateFilter to cardinalityProperties will return the approximate number of properties whose property key matches aggregateFilter from those sequences matching the filter and advancedFilter (or from all sequences if neither filter nor aggregateFilter are specified):

{
  "aggregate": "cardinalityProperties",
  "path": ["metadata"],
  "advancedFilter": {"prefix": {"property": ["name"], "value": "pump"}},
  "aggregateFilter": {"prefix": {"value": "t"}}
}

As we saw above, only one property matches:

{"items": [{"count": 1}]}

Note that aggregateFilter is also accepted when aggregate is set to cardinalityValues or cardinalityProperties. For those aggregations, the effect of any aggregateFilter could also be achieved via a similar advancedFilter. However, aggregateFilter is not accepted when aggregate is omitted or set to count.

Rate and concurrency limits

Rate and concurrency limits apply this endpoint. If a request exceeds one of the limits, it will be throttled with a 429: Too Many Requests response. More on limit types and how to avoid being throttled is described here.

Limit Per project Per user (identity)
Rate 15 requests per second 10 requests per second
Concurrency 6 concurrent requests 4 concurrent requests
Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Aggregates the sequences that match the given criteria.

One of
(Boolean filter (and (object) or or (object) or not (object))) or (Leaf filter (equals (object) or in (object) or range (object) or prefix (object) or exists (object) or containsAny (object) or containsAll (object) or search (object))) (TimeSeriesFilterLanguage)

A filter DSL (Domain Specific Language) to define advanced filter queries.

At the top level, an advancedFilter expression is either a single Boolean filter or a single leaf filter. Boolean filters contain other Boolean filters and/or leaf filters. The total number of filters may be at most 100, and the depth (the greatest number of times filters have been nested inside each other) may be at most 10. The search leaf filter may at most be used twice within a single advancedFilter, but all other filters can be used as many times as you like as long as the other limits are respected.

(Boolean filter (and (object) or or (object) or not (object))) or (Leaf filter (in (object) or range (object) or prefix (object))) (TimeSeriesAggregateFilter)

A filter DSL (Domain Specific Language) to define aggregate filters.

object (SequenceFilter)
aggregate
string
Value: "count"

The count aggregation gets the number of sequences that match the filter(s). This is the default aggregation, which will also be applied if aggregate is not specified.

Responses

Request samples

Content type
application/json
Example
{
  • "advancedFilter": {
    • "or": [
      ]
    },
  • "aggregateFilter": {
    • "and": [
      ]
    },
  • "filter": {
    • "name": "string",
    • "externalIdPrefix": "my.known.prefix",
    • "metadata": {
      },
    • "assetIds": [
      ],
    • "rootAssetIds": [
      ],
    • "assetSubtreeIds": [
      ],
    • "createdTime": {
      },
    • "lastUpdatedTime": {
      },
    • "dataSetIds": [
      ]
    },
  • "aggregate": "count"
}

Response samples

Content type
application/json
Example
{
  • "items": [
    • {
      }
    ]
}

Create sequences

Create one or more sequences.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Sequence to be stored.

required
Array of objects (PostSequenceDTO) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete rows

Deletes the given rows of the sequence. All columns are affected.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Indicate the sequences and the rows where data should be deleted.

required
Array of Select by Id (object) or Select by ExternalId (object) (SequenceDeleteDataRequest) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{ }

Delete sequences

Deletes the sequences with the specified IDs. If one or more of the sequences do not exist, the ignoreUnknownIds parameter controls what will happen: if it is true, the sequences that do exist will be deleted, and the request succeeds; if it is false or absent, nothing will be deleted, and the request fails.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Ids of the sequences to delete.

required
Array of Select by Id (object) or Select by ExternalId (object) [ 1 .. 1000 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{ }

Filter sequences

Retrieves a list of sequences 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 /sequences/search endpoint.
{"search": {"property": ["property"], "value": "example"}}

Supported properties

Property Type
["description"] string
["externalId"] string
["metadata", "<someCustomKey>"] string
["name"] string
["assetId"] number
["assetRootId"] number
["createdTime"] number
["dataSetId"] number
["id"] number
["lastUpdatedTime"] number
["accessCategories"] array of strings

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, sequences 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"]

Limits

The sort array must contain 1 to 2 elements.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Retrieves a list of sequences matching the given criteria.

object (SequenceFilter)
(Boolean filter (and (object) or or (object) or not (object))) or (Leaf filter (equals (object) or in (object) or range (object) or prefix (object) or exists (object) or containsAny (object) or containsAll (object) or search (object))) (TimeSeriesFilterLanguage)

A filter DSL (Domain Specific Language) to define advanced filter queries.

At the top level, an advancedFilter expression is either a single Boolean filter or a single leaf filter. Boolean filters contain other Boolean filters and/or leaf filters. The total number of filters may be at most 100, and the depth (the greatest number of times filters have been nested inside each other) may be at most 10. The search leaf filter may at most be used twice within a single advancedFilter, but all other filters can be used as many times as you like as long as the other limits are respected.

limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Returns up to this many results per page.

cursor
string
partition
string (Partition)

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.

Array of objects (TimeSeriesSortItem) [ 1 .. 2 ] items

Sort by array of selected properties.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "name": "string",
    • "externalIdPrefix": "my.known.prefix",
    • "metadata": {
      },
    • "assetIds": [
      ],
    • "rootAssetIds": [
      ],
    • "assetSubtreeIds": [
      ],
    • "createdTime": {
      },
    • "lastUpdatedTime": {
      },
    • "dataSetIds": [
      ]
    },
  • "advancedFilter": {
    • "or": [
      ]
    },
  • "limit": 100,
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
  • "partition": "1/10",
  • "sort": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Insert rows

Inserts rows into a sequence. This overwrites data in rows and columns that exist.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Data posted.

required
Array of Select by Id (object) or Select by ExternalId (object) (SequencePostData) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{ }

List sequences

List sequences. Use nextCursor to paginate through the results.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

partition
string
Example: partition=1/10

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.

limit
integer [ 1 .. 1000 ]
Default: 25

Limits the number of results to be returned. The server returns a maximum of 1000 results even if you specify a higher limit.

Responses

Request samples

const sequences = await client.sequences.list({ filter: { name: 'sequence_name' } });

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Retrieve last row

Retrieves the last row in one or more sequences. Note that the last row in a sequence is the one with the highest row number, which is not necessarily the one that was ingested most recently.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Description of data requested.

One of
columns
Array of strings [ 1 .. 400 ] items

Columns to include. Specified as a list of the externalId of each column to include. If this filter isn't set, all available columns will be returned.

before
integer <int64> >= 1

Get rows up to, but not including, this row number.

id
required
integer <int64> (CogniteInternalId) [ 1 .. 9007199254740991 ]

A server-generated ID for the object.

Responses

Request samples

Content type
application/json
Example
{
  • "columns": [
    • "string"
    ],
  • "before": 1,
  • "id": 1
}

Response samples

Content type
application/json
{
  • "id": 1112,
  • "externalId": "DL/DRILL412/20190103/T3",
  • "columns": [
    • {
      },
    • {
      },
    • {
      }
    ],
  • "rows": [
    • {
      }
    ]
}

Retrieve rows

Processes data requests and returns the result. Note that this operation uses a dynamic limit on the number of rows returned based on the number and type of columns; use the provided cursor to paginate and retrieve all data.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Description of data requested.

One of
start
integer <int64>
Default: 0

Lowest row number included.

end
integer <int64>

Get rows up to, but excluding, this row number. Default - No limit.

limit
integer <int32> [ 1 .. 10000 ]
Default: 100

Maximum number of rows returned in one request. API might return less even if there's more data, but it will provide a cursor for continuation. If there's more data beyond this limit, a cursor will be returned to simplify further fetching of data.

cursor
string

Cursor for pagination returned from a previous request. Apart from this cursor, the rest of the request object is the same as for the original request.

columns
Array of strings [ 1 .. 400 ] items

Columns to include. Specified as a list of the externalId of each column to include. If this filter isn't set, all available columns will be returned.

id
required
integer <int64> (CogniteInternalId) [ 1 .. 9007199254740991 ]

A server-generated ID for the object.

Responses

Request samples

Content type
application/json
Example
{
  • "start": 0,
  • "end": 1,
  • "limit": 1,
  • "cursor": "string",
  • "columns": [
    • "string"
    ],
  • "id": 1
}

Response samples

Content type
application/json
{
  • "id": 1112,
  • "externalId": "DL/DRILL412/20190103/T3",
  • "columns": [
    • {
      },
    • {
      },
    • {
      }
    ],
  • "rows": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Retrieve sequences

Retrieves one or more sequences by ID or external ID. The response returns the sequences in the same order as in the request.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Ids of the sequences

required
Array of Select by Id (object) or Select by ExternalId (object) [ 1 .. 1000 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Search sequences

Retrieves a list of sequences matching the given criteria. This operation doesn't support pagination.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Retrieves a list of sequences matching the given criteria. This operation doesn't support pagination.

object (SequenceFilter)
object (SequenceSearch)
limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Returns up to this many results.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "name": "string",
    • "externalIdPrefix": "my.known.prefix",
    • "metadata": {
      },
    • "assetIds": [
      ],
    • "rootAssetIds": [
      ],
    • "assetSubtreeIds": [
      ],
    • "createdTime": {
      },
    • "lastUpdatedTime": {
      },
    • "dataSetIds": [
      ]
    },
  • "search": {
    • "name": "string",
    • "description": "string",
    • "query": "string"
    },
  • "limit": 100
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Update sequences

Updates one or more sequences. Fields outside of the request remain unchanged.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Patch definition

required
Array of Select by Id (object) or Select by ExternalId (object) (SequencesUpdate) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Seismic

A seismic object is a no-copy view into seismic stores. Once you have defined the object, either via a polygon to "cut out" from the origin seismic store or via an explicit trace-by-trace mapping, you cannot modify it. You can assign seismic objects to partitions and restrict user access to each partition. That way, seismic objects are the most granular unit of access control. Each seismic object has one corresponding partition. If a user is restricted to a specific partition, they will only be able to view the seismic objects that have been assigned to that partition.

Download a seismic object as a SEG-Y file

Retrieves a SEG-Y file with all traces contained within the given seismic object.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
seismicId
required
integer

The identifier of a seismic object

Responses

Response samples

Content type
application/json
{
  • "error": {
    • "code": 401,
    • "message": "Could not authenticate.",
    • "missing": [
      ],
    • "duplicated": [
      ]
    }
}

Download multiple seismic objects as a ZIP archive

Download multiple seismic objects specified by the filter, as a streamed ZIP archive file.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

The filter that determines the seismic objects to return.

One of
items
required
Array of integers <int64> (CogniteInternalId) [ items <int64 > [ 1 .. 9007199254740991 ] ]

The list of seismic objects to include in the ZIP archive, specified by internal id.

Responses

Request samples

Content type
application/json
Example
{
  • "items": [
    • 1
    ]
}

Response samples

Content type
application/json
{
  • "error": {
    • "code": 401,
    • "message": "Could not authenticate.",
    • "missing": [
      ],
    • "duplicated": [
      ]
    }
}

3D Models

Create 3D models

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

The models to create.

required
Array of objects (CreateModel3D) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete 3D models

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of models to delete.

required
Array of objects (DataIdentifier) [ 1 .. 1000 ] items unique

List of ID objects

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{ }

List 3D models

Retrieves a list of all models in a project. This operation supports pagination. You can filter out all models without a published revision.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

published
boolean

Filter based on whether or not it has published revisions.

Responses

Request samples

const models3D = await client.models3D.list({ published: true });

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Retrieve a 3D model

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
modelId
required
integer <int64>

Model ID.

Responses

Request samples

await client.models3D.retrieve(3744350296805509);

Response samples

Content type
application/json
{
  • "name": "My Model",
  • "id": 1000,
  • "createdTime": 0,
  • "dataSetId": 1,
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    }
}

Update 3D models

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of changes.

required
Array of objects (UpdateModel3D) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

3D Model Revisions

Create 3D revisions

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
modelId
required
integer <int64>

Model ID.

Request Body schema: application/json

The revisions to create.

required
Array of objects (CreateRevision3D) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete 3D revisions

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
modelId
required
integer <int64>

Model ID.

Request Body schema: application/json

List of revisions ids to delete.

required
Array of objects (DataIdentifier) [ 1 .. 1000 ] items unique

List of ID objects

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{ }

Filter 3D nodes

List nodes in a project, filtered by node names or node property values specified by supplied filters. This operation supports pagination and partitions. If the model revision is still being processed, you will get a HTTP status 400 when accessing nodes too early. Wait until the retrieve revision response returns "status":"Done" before calling nodes endpoints.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

Request Body schema: application/json
One of
object (Node3DPropertyFilter)

Filters used in the search.

limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to return.

cursor
string
partition
string (Partition)

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.

Responses

Request samples

Content type
application/json
Example
{
  • "filter": {
    • "properties": {
      }
    },
  • "limit": 100,
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
  • "partition": "1/10"
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Get 3D nodes by ID

Retrieves specific nodes given by a list of IDs.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

Request Body schema: application/json

The request body containing the IDs of the nodes to retrieve. Will return error 400 if the revision is still being processed.

required
Array of objects (Node3DId) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

List 3D ancestor nodes

Retrieves a list of ancestor nodes of a given node, including itself, in the hierarchy of the 3D model. This operation supports pagination. Will return error 400 if the revision is still being processed.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

nodeId
required
integer <int64>

ID of the node to get the ancestors of.

query Parameters
cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

Responses

Request samples

const nodes3d = await client.revisions3D.list3DNodeAncestors(8252999965991682, 4190022127342195, 572413075141081);

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

List 3D nodes

Retrieves a list of nodes from the hierarchy in the 3D model. You can also request a specific subtree with the 'nodeId' query parameter and limit the depth of the resulting subtree with the 'depth' query parameter. By default, nodes are returned in order of ascending treeIndex. We suggest trying to set the query parameter sortByNodeId to true to check whether it makes your use case faster. The partition parameter can only be used if sortByNodeId is set to true. This operation supports pagination. If the model revision is still being processed, you will get a HTTP status 400 when accessing nodes too early. Wait until the retrieve revision response returns "status":"Done" before calling nodes endpoints.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

query Parameters
partition
string
Example: partition=1/10

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.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

depth
integer <int32>

Get sub nodes up to this many levels below the specified node. Depth 0 is the root node.

nodeId
integer <int64>

ID of a node that are the root of the subtree you request (default is the root node).

sortByNodeId
boolean
Default: false

Enable sorting by nodeId. When this parameter is true, nodes will be listed in order of ascending nodeId. Enabling this option will likely result in faster response for many requests.

properties
string <jsonObject(jsonObject(string))>

Example: {"category1":{"property1":"value1"}}

Filter for node properties. Only nodes that match all the given properties exactly will be listed. The filter must be a JSON object with the same format as the properties field.

Responses

Request samples

const nodes3d = await client.revisions3D.list3DNodes(8252999965991682, 4190022127342195);

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

List 3D revision logs

List log entries for the revision

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

query Parameters
severity
integer <int64>
Default: 5

Minimum severity to retrieve (3 = INFO, 5 = WARN, 7 = ERROR).

Responses

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

List 3D revisions

Retrieves a list of all revisions of a model. This operation supports pagination. You can also filter revisions if they are marked as published or not by using the query param published.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
modelId
required
integer <int64>

Model ID.

query Parameters
cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

published
boolean

Filter based on published status.

Responses

Request samples

const revisions3D = await client.revisions3D.list(324566546546346);

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

List available outputs

Retrieve a list of available outputs for a processed 3D model. An output can be a format that can be consumed by a viewer (e.g. Reveal) or import in external tools. Each of the outputs will have an associated version which is used to identify the version of output format (not the revision of the processed output). Note that the structure of the outputs will vary and is not covered here.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

query Parameters
format
string

Format identifier, e.g. 'ept-pointcloud' (point cloud). Well known formats are: 'ept-pointcloud' (point cloud data) or 'reveal-directory' (output supported by Reveal). 'all-outputs' can be used to retrieve all outputs for a 3D revision. Note that some of the outputs are internal, where the format and availability might change without warning.

Responses

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Retrieve a 3D revision

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

Responses

Request samples

const revisions3D = await client.revisions3D.retrieve(8252999965991682, 4190022127342195)

Response samples

Content type
application/json
{
  • "id": 1000,
  • "fileId": 1000,
  • "published": false,
  • "rotation": [
    • 0,
    • 0,
    • 0
    ],
  • "scale": [
    • 1,
    • 1,
    • 1
    ],
  • "translation": [
    • 0,
    • 0,
    • 0
    ],
  • "camera": {
    • "target": [
      ],
    • "position": [
      ]
    },
  • "status": "Done",
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    },
  • "thumbnailThreedFileId": 1000,
  • "assetMappingCount": 0,
  • "createdTime": 0
}

Update 3D revision thumbnail

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

Request Body schema: application/json

The request body containing the file ID of the thumbnail image (from Files API).

fileId
required
integer <int64>

File ID of thumbnail file in Files API. Only JPEG and PNG files are supported.

Responses

Request samples

Content type
application/json
{
  • "fileId": 0
}

Response samples

Content type
application/json
{ }

Update 3D revisions

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
modelId
required
integer <int64>

Model ID.

Request Body schema: application/json

List of changes.

required
Array of objects (UpdateRevision3D) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

3D Files

Retrieve a 3D file

Retrieve the contents of a 3D file.

This endpoint supported tag-based caching.

This endpoint is only compatible with 3D file IDs from the 3D API, and not compatible with file IDs from the Files API.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
threedFileId
required
integer <int64>

The ID of the 3D file to retrieve.

Responses

Request samples

await client.files3D.retrieve(3744350296805509);

Response samples

Content type
application/json
{
  • "error": {
    • "code": 401,
    • "message": "Could not authenticate.",
    • "missing": [
      ],
    • "duplicated": [
      ]
    }
}

3D Asset Mapping

Create 3D asset mappings

Create asset mappings

Asset references when creating a mapping - through asset ids - are allowed to be invalid. They are NOT maintained by any means from CDF, meaning they will be stored until the reference is removed through the delete endpoint of 3d asset mappings.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

Request Body schema: application/json

The asset mappings to create.

required
Array of objects (CreateAssetMapping3D) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete 3D asset mappings

Delete a list of asset mappings

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

Request Body schema: application/json

The IDs of the asset mappings to delete.

required
Array of objects (DeleteAssetMapping3D) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{ }

Filter 3D asset mappings

Lists 3D assets mappings that match the specified filter parameter. Only one type of filter can be specified for each request, either assetIds, nodeIds or treeIndexes.

Asset references obtained from a mapping - through asset ids - may be invalid, simply by the non-transactional nature of HTTP. They are NOT maintained by any means from CDF, meaning they will be stored until the reference is removed through the delete endpoint of 3d asset mappings.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

Request Body schema: application/json

The filter for asset mappings to get.

AssetMapping3DAssetFilter (object) or AssetMapping3DNodeFilter (object) or AssetMapping3DTreeIndexFilter (object)
limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Limits the number of results to return.

cursor
string

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "assetIds": [
      ]
    },
  • "limit": 100,
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo"
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

List 3D asset mappings

List all asset mappings

Asset references obtained from a mapping - through asset ids - may be invalid, simply by the non-transactional nature of HTTP. They are NOT maintained by any means from CDF, meaning they will be stored until the reference is removed through the delete endpoint of 3d asset mappings.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
modelId
required
integer <int64>

Model ID.

revisionId
required
integer <int64>

Revision ID.

query Parameters
cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

nodeId
integer <int64>
assetId
integer <int64>
intersectsBoundingBox
string

Example: {"min":[0.0, 0.0, 0.0], "max":[1.0, 1.0, 1.0]}

If given, only return asset mappings for assets whose bounding box intersects the given bounding box.

Must be a JSON object with min, max arrays of coordinates.

Responses

Request samples

const mappings3D = await client.assetMappings3D.list(3244265346345, 32423454353545);

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

List mappings for one assetID across all 3D models

Retrieves a list of node IDs from the hierarchy of all available 3D models which are mapped to the supplied asset ID. If a node ID is mapped to the asset ID but is invalid or does not exist anymore, it will be omitted from the results.

Asset references obtained from a mapping - through asset id - may be invalid, simply by the non-transactional nature of HTTP. They are NOT maintained by any means from CDF, meaning they will be stored until the reference is removed through the delete endpoint of 3d asset mappings.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
assetId
required
integer <int64>

Asset ID.

query Parameters
cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

Responses

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Entity matching

The entity matching contextualization endpoints lets you match CDF resources. For example, you can match time series to assets. The model uses similarity between string-fields from the source and the target to find potential matches, for instance the source name and the target name. The exact algorithm may change over time.

Create entity matcher model

Train a model that predicts matches between entities (for example, time series names to asset names). This is also known as fuzzy joining. If there are no trueMatches (labeled data), you train a static (unsupervised) model, otherwise a machine learned (supervised) model is trained.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
sources
required
Array of objects (Sources) [ 0 .. 2000000 ] items

List of custom source object to match from, for example, time series. String key -> value. Only string values are considered in the matching. Both id and externalId fields are optional, only mandatory if the item is to be referenced in trueMatches.

targets
required
Array of objects (Targets) [ 1 .. 2000000 ] items

List of custom target object to match to, for example, assets. String key -> value. Only string values are considered in the matching. Both id and externalId fields are optional, only mandatory if the item is to be referenced in trueMatches.

Array of objects or objects or objects or objects (TrueMatches) [ 1 .. 2000000 ] items

A list of confirmed source/target matches, which will be used to train the model. If omitted, an unsupervised model is trained.

externalId
string (CogniteExternalId) <= 255 characters

The external ID provided by the client. Must be unique for the resource type.

name
string (ModelName) <= 256 characters

User defined name.

description
string (ModelDescription) <= 500 characters

User defined description.

featureType
string
Default: "simple"
Enum: "simple" "insensitive" "bigram" "frequencyweightedbigram" "bigramextratokenizers" "bigramcombo"

Each feature type defines one combination of features that will be created and used in the entity matcher model. All features are based on matching tokens. Tokens are defined at the top of the Entity matching section. The options are:

  • Simple: Calculates the cosine-distance similarity score for each of the pairs of fields defined in matchFields. This is the fastest option.
  • Insensitive: Similar to Simple, but ignores lowercase/uppercase differences.
  • Bigram: Similar to simple, but adds similarity score based on matching bigrams of the tokens.
  • FrequencyWeightedBigram: Similar to bigram, but give higher weights to less commonly occurring tokens.
  • BigramExtraTokenizers: Similar to bigram, but able to learn that leading zeros, spaces, and uppercase/lowercase differences should be ignored in matching.
  • BigramCombo: Calculates all of the above options, relying on the model to determine the appropriate features to use. Hence, this option is only appropriate if there are labeled data/trueMatches. This is the slowest option.
Array of objects (MatchFields)
Default: [{"source":"name","target":"name"}]

List of pairs of fields from the target and source items, used to calculate features. All source and target items should have all the source and target fields specified here.

classifier
string (Classifier)
Default: "randomforest"
Enum: "randomforest" "decisiontree" "logisticregression" "augmentedlogisticregression" "augmentedrandomforest"

The classifier used in the model. Only relevant if there are trueMatches/labeled data and a supervised model is fitted.

ignoreMissingFields
boolean (IgnoreMissingFields)
Default: false

If True, replaces missing fields in sources or targets entities, for fields set in set in matchFields, with empty strings. Else, returns an error if there are missing data.

Responses

Request samples

Content type
application/json
{
  • "sources": [
    • {
      }
    ],
  • "targets": [
    • {
      }
    ],
  • "trueMatches": [
    • {
      }
    ],
  • "externalId": "my.known.id",
  • "name": "simple_model_1",
  • "description": "Simple model 1",
  • "featureType": "simple",
  • "matchFields": [
    • {
      },
    • {
      }
    ],
  • "classifier": "randomforest",
  • "ignoreMissingFields": true
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "externalId": "my.known.id",
  • "status": "Queued",
  • "createdTime": 0,
  • "startTime": 0,
  • "statusTime": 0,
  • "errorMessage": null,
  • "name": "simple_model_1",
  • "description": "Simple model 1",
  • "featureType": "simple",
  • "matchFields": [
    • {
      },
    • {
      }
    ],
  • "ignoreMissingFields": true,
  • "classifier": "randomforest",
  • "originalId": 111
}

Delete entity matcher model

Deletes an entity matching model. Currently, this is a soft delete, and only removes the entry from listing.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
required
Array of objects or objects (OneOfId)

List of ids or externalIds of models.

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      },
    • {
      }
    ]
}

Response samples

Content type
application/json
{ }

Filter models

Use filtering options to find entity matcher models.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
limit
integer <int32> [ 1 .. 1000 ]
Default: 100

<- Limits the number of results to return.

required
object

Filter on models with strict matching.

Responses

Request samples

Content type
application/json
{
  • "limit": 100,
  • "filter": {
    • "featureType": "simple",
    • "classifier": "randomforest",
    • "originalId": 111,
    • "name": "simple_model_1",
    • "description": "Simple model 1"
    }
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

List entity matching models

List all available entity matching models.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
limit
integer >= 1
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

Responses

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Predict matches

Predicts entity matches using a trained model. Note: 'assetsAcl:READ' capability is required unless both sources and targets are specified in the request. Also note that the header of a successful response contains a X-Job-Token which allows to fetch the result of the job at /context/entitymatching/jobs/{jobId} without requiring 'assetsAcl:READ'.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
One of
id
required
integer <int64> [ 1 .. 9007199254740991 ]

The ID of the model that is used to predict matches.

sources
Array of objects [ 0 .. 2000000 ] items

List of source entities to predict matches for, for example, time series. If omitted, will use sources from create and assetsAcl:READ capability will be required for the request.

targets
Array of objects [ 1 .. 2000000 ] items

List of potential target entities to match to one or more of the source entities, for example, assets. If omitted, will use targets from create and assetsAcl:READ capability will be required for the request.

numMatches
integer [ 0 .. 100 ]

The maximum number of results to return for each source entity.

scoreThreshold
number [ 0 .. 1 ]

Only return matches with score above this threshold.

Responses

Request samples

Content type
application/json
{
  • "externalId": "my.known.id",
  • "sources": [
    • {
      }
    ],
  • "targets": [
    • {
      }
    ],
  • "numMatches": 3,
  • "scoreThreshold": 0.7
}

Response samples

Content type
application/json
{
  • "jobId": 123,
  • "status": "Queued",
  • "createdTime": 0,
  • "startTime": 0,
  • "statusTime": 0,
  • "errorMessage": null
}

Re-fit entity matcher model

Creates a new model by re-training an existing model on existing data but with additional true matches. The old model is not changed. The new model gets a new id and new external id if newExternalId is set, or no external id if newExternalId is not set. Use for efficient re-training of the model after a user creates additional confirmed matches.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
One of
id
required
integer <int64> [ 1 .. 9007199254740991 ]

The ID of the original model.

newExternalId
string <= 255 characters

ExternalId for the new refitted model provided by client. Must be unique within the project.

required
Array of objects or objects or objects or objects [ 1 .. 2000000 ] items

List of additional confirmed matches used to train the model. The new model uses a combination of this and trueMatches from the orginal model. If there are identical match-from ids, the pair from the original model is dropped.

sources
Array of objects [ 0 .. 2000000 ] items

List of source entities, for example, time series. If omitted, will use data from fit.

targets
Array of objects [ 1 .. 2000000 ] items

List of target entities, for example, assets. If omitted, will use data from fit.

Responses

Request samples

Content type
application/json
{
  • "externalId": "my.known.id",
  • "newExternalId": "my.known.id",
  • "trueMatches": [
    • {
      }
    ],
  • "sources": [
    • {
      }
    ],
  • "targets": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "externalId": "my.known.id",
  • "status": "Queued",
  • "createdTime": 0,
  • "startTime": 0,
  • "statusTime": 0,
  • "errorMessage": null,
  • "name": "simple_model_1",
  • "description": "Simple model 1",
  • "featureType": "simple",
  • "matchFields": [
    • {
      },
    • {
      }
    ],
  • "ignoreMissingFields": true,
  • "classifier": "randomforest",
  • "originalId": 111
}

Retrieve an entity matching model by the ID of the model

Shows the status of the model. If the status is completed, shows the parameters used to train the model.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
id
required
integer <int64> (CogniteInternalId) [ 1 .. 9007199254740991 ]

A server-generated ID for the object.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "externalId": "my.known.id",
  • "status": "Queued",
  • "createdTime": 0,
  • "startTime": 0,
  • "statusTime": 0,
  • "errorMessage": null,
  • "name": "simple_model_1",
  • "description": "Simple model 1",
  • "featureType": "simple",
  • "matchFields": [
    • {
      },
    • {
      }
    ],
  • "ignoreMissingFields": true,
  • "classifier": "randomforest",
  • "originalId": 111
}

Retrieve entity matcher predict results

Get the results from a predict job. Note: 'assetsAcl:READ' capability is required, unless you specify a valid X-Job-Token in the request header. The X-Job-Token is provided in the response header of the initial call to /context/entitymatching/predict

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
jobId
required
integer <int64> (JobId)
Example: 123

Contextualization job ID.

header Parameters
X-Job-Token
string (JobToken)

A string token that can be attached to the header of a request fetching the job status. Authenticates the user fetching the job status as the same one who originally posted the job.

Responses

Response samples

Content type
application/json
{
  • "status": "Queued",
  • "createdTime": 0,
  • "startTime": 0,
  • "statusTime": 0,
  • "errorMessage": null,
  • "jobId": 123,
  • "items": [
    • {
      }
    ]
}

Retrieve entity matching models

Retrieve entity matching models by IDs or external IDs.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
required
Array of objects or objects (OneOfId)

List of ids or externalIds of models.

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      },
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Update entity matching models

Update entity matching models by IDs or external IDs.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
required
Array of ModelChangeById (object) or ModelChangeByExternalId (object) (ModelChange)

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Engineering diagrams

Convert a diagram to image format

Convert interactive engineering diagrams to image format, with highlighted annotations. Supported input file mime_types are application/pdf, image/jpeg, image/png, image/tiff. Supported output image formats are PNG and SVG, only the svg embeds the input annotations.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
required
Array of objects or objects (DiagramConvertRequestSchema) [ 1 .. 50 ] items

An array of files and annotations to create interactive diagrams.

grayscale
boolean (Grayscale)
Default: true

Return the SVG version in grayscale colors only (reduces the file size).

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "grayscale": true
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "jobId": 123,
  • "status": "Queued",
  • "createdTime": 0,
  • "startTime": 0,
  • "statusTime": 0,
  • "errorMessage": null,
  • "grayscale": true
}

Detect annotations in engineering diagrams

Detect annotations in engineering diagrams. Note: All users in a CDF project with assets read-all and files read-all capabilities can access data sent to this endpoint. Supported input file mime_types are application/pdf, image/jpeg, image/png, image/tiff.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
required
Array of objects or objects (FileReferenceWithPageRange) [ 1 .. 50 ] items

Files to run entity detection on.

entities
required
Array of objects (DiagramDetectEntities) [ 1 .. 500000 ] items [ items <= 256 properties ]

A list of entities to look for. For example, all the assets under a root node. The searchField determines the strings that identify the entities.

searchField
string (DiagramSearchField)
Default: "name"

This field determines the string to search for and to identify object entities.

partialMatch
boolean (DiagramPartialMatch)
Default: false

Allow partial (fuzzy) matching of entities in the engineering diagrams. Creates a match only when it is possible to do so unambiguously.

minTokens
integer (DiagramMinTokens)
Default: 2

Each detected item must match the detected entity on at least this number of tokens. A token is a substring of consecutive letters or digits.

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "entities": [
    • {
      },
    • {
      }
    ],
  • "searchField": "userDefinedField",
  • "partialMatch": false,
  • "minTokens": 2
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "jobId": 123,
  • "status": "Queued",
  • "createdTime": 0,
  • "startTime": 0,
  • "statusTime": 0,
  • "errorMessage": null,
  • "searchField": "userDefinedField",
  • "partialMatch": false,
  • "minTokens": 2
}

Get the results for converting an engineering diagram to an image

Get the results for converting an engineering diagram to SVG and PNG formats.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
jobId
required
integer <int64> (JobId)
Example: 123

Contextualization job ID.

Responses

Response samples

Content type
application/json
{}

Retrieve engineering diagram detect results

Get the results from an engineering diagram detect job.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
jobId
required
integer <int64> (JobId)
Example: 123

Contextualization job ID.

Responses

Response samples

Content type
application/json
{
  • "jobId": 123,
  • "status": "Queued",
  • "items": [
    • {
      }
    ],
  • "createdTime": 0,
  • "startTime": 0,
  • "statusTime": 0,
  • "errorMessage": null,
  • "searchField": "userDefinedField",
  • "partialMatch": false,
  • "minTokens": 2
}

Vision

The Vision contextualization endpoints enable extraction of information from imagery data based on their visual content. For example, you can detect external ID or name of assets, detect and read value of gauges or identify common industrial objects in images.

This service has support for batch processing which enables processing of multiple image files via an asynchronous prediction request. A new contextualization job is triggered by sending a POST request to the service. The response of the POST request contains a job ID, which can then be used to make subsequent calls to check the status and retrieve the results of the job once it is completed.

Extract features from images

Start an asynchronous prediction job for extracting features such as text, asset tags or industrial objects from images. The response of the POST request contains a job ID, which can be used to make subsequent (GET) calls to check the status and retrieve the results of the job (see Retrieve results from a feature extraction job).

It is possible to have up to 20 concurrent jobs per CDF project.

The files referenced by items in the request body must fulfill the following requirements:

  • Must have file extension: .jpeg, .jpg or .png
  • Must have image/png or image/jpeg as mimeType

New feature extractors may be added in the future.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
header Parameters
cdf-version
string
Example: alpha

cdf version header. Use this to specify the requested CDF release.

Request Body schema: application/json

A request for running an extract job.

required
Array of objects or objects (FileReference) [ 1 .. 100 ]

List of image files to be analyzed by the feature extractors.

required
Array of TextDetection (string) or AssetTagDetection (string) or PeopleDetection (string) or IndustrialObjectDetection (string) or PersonalProtectiveEquipmentDetection (string) or DialGaugeDetection (string) or LevelGaugeDetection (string) or DigitalGaugeDetection (string) or ValveDetection (string) (VisionExtractFeature) [ 1 .. 3 ] unique

The type of detections to perform. New feature extractors may appear. You can use up to three feature extractors per request.

object (FeatureParameters)

Feature-specific parameters. New feature extractor parameters may appear.

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "features": [
    • "TextDetection",
    • "AssetTagDetection",
    • "PeopleDetection"
    ],
  • "parameters": {
    • "textDetectionParameters": {
      },
    • "assetTagDetectionParameters": {
      },
    • "peopleDetectionParameters": {
      }
    }
}

Response samples

Content type
application/json
{
  • "status": "Queued",
  • "createdTime": 0,
  • "startTime": 0,
  • "statusTime": 0,
  • "errorMessage": null,
  • "jobId": 123,
  • "items": [
    • {
      }
    ],
  • "features": [
    • "TextDetection",
    • "AssetTagDetection",
    • "PeopleDetection"
    ],
  • "parameters": {
    • "textDetectionParameters": {
      },
    • "assetTagDetectionParameters": {
      },
    • "peopleDetectionParameters": {
      }
    }
}

Retrieve results from a feature extraction job on images

Retrieve results from a feature extraction job on images.

Note that since files are split up into batches and processed independently of each other, the items in successfully completed batches will be returned even if files in other batches are still being processed. The job status will be Running until all batches have been processed. If one of the items in a batch fails, the results from items in other completed batches will still be returned. The corresponding items and error message(s) of failed batches will be populated in failedItems. Additionally, the status of the job is set to Completed if at least one batch is successfully completed, otherwise the status is set to Failed.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
jobId
required
integer <int64> (JobId)
Example: 123

Contextualization job ID.

header Parameters
cdf-version
string
Example: alpha

cdf version header. Use this to specify the requested CDF release.

Responses

Request samples

// get an existing job, wait for it to complete, and get the results
const { items } = await client.vision.getExtractJob(1, true);
items.forEach((item) => {
  const predictions = item.predictions;
  // do something with the predictions
})

Response samples

Content type
application/json
{
  • "status": "Queued",
  • "createdTime": 0,
  • "startTime": 0,
  • "statusTime": 0,
  • "errorMessage": null,
  • "jobId": 123,
  • "items": [
    • {
      }
    ],
  • "failedItems": [
    • {
      }
    ],
  • "parameters": {
    • "textDetectionParameters": {
      },
    • "assetTagDetectionParameters": {
      },
    • "peopleDetectionParameters": {
      }
    }
}

Raw

Manage data in the raw NoSQL database. Each project will have a variable number of raw databases, each of which will have a variable number of tables, each of which will have a variable number of key-value objects. Only queries on key are supported through this API.

Create databases

Create databases in a project. It is possible to post a maximum of 1000 databases per request.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of names of databases to be created.

Array of objects (RawDB)

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Create tables in a database

Create tables in a database. It is possible to post a maximum of 1000 tables per request.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
dbName
required
string

Name of the database to create tables in.

query Parameters
ensureParent
boolean
Default: false

Create database if it doesn't exist already

Request Body schema: application/json

List of tables to create.

Array of objects (RawDBTable)

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete databases

It deletes a database, but fails if the database is not empty and recursive is set to false (default).

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of names of the databases to be deleted.

Array of objects (RawDB)
recursive
boolean
Default: false

When true, tables of this database are deleted with the database.

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "recursive": false
}

Response samples

Content type
application/json
{ }

Delete rows in a table

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
dbName
required
string [ 1 .. 32 ] characters

Name of the database containing the rows.

tableName
required
string [ 1 .. 64 ] characters

Name of the table containing the rows.

Request Body schema: application/json

Keys to the rows to delete.

Array of objects (RawDBRowKey)

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{ }

Delete tables in a database

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
dbName
required
string

Name of the database to delete tables in.

Request Body schema: application/json

List of tables to delete.

Array of objects (RawDBTable)

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{ }

Insert rows into a table

Insert rows into a table. It is possible to post a maximum of 10000 rows per request. It will replace the columns of an existing row if the rowKey already exists.

The rowKey is limited to 1024 characters which also includes Unicode characters. The maximum size of columns are 5 MiB, however the maximum size of one column name and value is 2621440 characters each. If you want to store huge amount of data per row or column we recommend using the Files API to upload blobs, then reference it from the Raw row.

The columns object is a key value object, where the key corresponds to the column name while the value is the column value. It supports all the valid types of values in JSON, so number, string, array, and even nested JSON structure (see payload example to the right).

Note There is no rollback if an error occurs, which means partial data may be written. However, it's safe to retry the request, since this endpoint supports both update and insert (upsert).

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
dbName
required
string [ 1 .. 32 ] characters

Name of the database.

tableName
required
string [ 1 .. 64 ] characters

Name of the table.

query Parameters
ensureParent
boolean
Default: false

Create database/table if it doesn't exist already

Request Body schema:

List of rows to create.

Array of objects (RawDBRowInsert)

Responses

Request samples

Content type
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{ }

List databases

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
limit
integer <int32> [ 1 .. 1000 ]
Default: 25

Limit on the number of databases to be returned.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

Responses

Request samples

const databases = await client.raw.listDatabases();

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

List tables in a database

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
dbName
required
string

The name of a database to retrieve tables from.

query Parameters
limit
integer <int32> [ 1 .. 1000 ]
Default: 25

Limit on the number of tables to be returned.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

Responses

Request samples

const tables = await client.raw.listTables('My company');

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Retrieve cursors for parallel reads

Retrieve cursors based on the last updated time range. Normally this endpoint is used for reading in parallel.

Each cursor should be supplied as the 'cursor' query parameter on GET requests to Read Rows. Note that the 'minLastUpdatedTime' and the 'maxLastUpdatedTime' query parameter on Read Rows are ignored when a cursor is specified.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
dbName
required
string

Name of the database.

tableName
required
string

Name of the table.

query Parameters
minLastUpdatedTime
integer <int64> (EpochTimestamp) >= 0

An exclusive filter, specified as the number of milliseconds that have elapsed since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

maxLastUpdatedTime
integer <int64> (EpochTimestamp) >= 0

An inclusive filter, specified as the number of milliseconds that have elapsed since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

numberOfCursors
integer <int32> [ 1 .. 10000 ]

The number of cursors to return, by default it's 10.

Responses

Response samples

Content type
application/json
{
  • "items": [
    • "string"
    ]
}

Retrieve row by key

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
dbName
required
string [ 1 .. 32 ] characters

Name of the database to retrieve the row from.

tableName
required
string [ 1 .. 64 ] characters

Name of the table to retrieve the row from.

rowKey
required
string

Row key of the row to retrieve.

Responses

Request samples

await client.raw.retrieveRow('My company', 'Customers', 'customer1');

Response samples

Content type
application/json
{
  • "key": "string",
  • "columns": { },
  • "lastUpdatedTime": 0
}

Retrieve rows from a table

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
dbName
required
string

Name of the database.

tableName
required
string

Name of the table.

query Parameters
limit
integer <int32> [ 1 .. 10000 ]
Default: 25

Limit the number of results. The API may return fewer than the specified limit.

columns
string
Example: columns=column1,column2

Ordered list of column keys, separated by commas. Leave empty for all, use single comma to retrieve only row keys.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

minLastUpdatedTime
integer <int64> (EpochTimestamp) >= 0

An exclusive filter, specified as the number of milliseconds that have elapsed since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

maxLastUpdatedTime
integer <int64> (EpochTimestamp) >= 0

An inclusive filter, specified as the number of milliseconds that have elapsed since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds.

Responses

Request samples

await client.raw.listRows('My company', 'Employees', { columns: ['last_name'] });

Response samples

Content type
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Extraction Pipelines

Extraction Pipeline objects represent the applications and software that are deployed to ingest operational data into CDF. An extraction pipeline can consist of a number of different software components between the source system and CDF. The extraction pipeline object represents the software component that actually sends the data to CDF. Two examples are Cognite extractors and third party ETL tools such as Microsoft Azure or Informatica PowerCenter

Create extraction pipelines

Creates multiple new extraction pipelines. A maximum of 1000 extraction pipelines can be created per request.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
required
Array of objects (CreateExtPipe) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Delete extraction pipelines

Delete extraction pipelines for given list of ids and externalIds. When the extraction pipeline is deleted, all extraction pipeline runs related to the extraction pipeline are automatically deleted.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
required
Array of ExtPipeInternalId (object) or ExtPipeExternalId (object) (ExtPipeId) [ 1 .. 1000 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{ }

Filter extraction pipelines

Use advanced filtering options to find extraction pipelines.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
object (ExtPipesFilter)
limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Limits the number of results to return.

cursor
string

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "externalIdPrefix": "string",
    • "name": "string",
    • "description": "string",
    • "dataSetIds": [
      ],
    • "schedule": "string",
    • "contacts": [
      ],
    • "rawTables": [
      ],
    • "metadata": {
      },
    • "source": "string",
    • "documentation": "string",
    • "createdBy": "string",
    • "createdTime": {
      },
    • "lastUpdatedTime": {
      }
    },
  • "limit": 100,
  • "cursor": "string"
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

List extraction pipelines

Returns a list of all extraction pipelines for a given project

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

Responses

Request samples

ep_list = client.extraction_pipelines.list(limit=5)

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Retrieve an extraction pipeline by its ID.

Retrieve an extraction pipeline by its ID. If you want to retrieve extraction pipelines by externalIds, use Retrieve extraction pipelines instead.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
id
required
integer <int64> (CogniteInternalId) [ 1 .. 9007199254740991 ]

A server-generated ID for the object.

Responses

Request samples

res = client.extraction_pipelines.retrieve(id=1)

res = client.extraction_pipelines.retrieve(external_id="1")

Response samples

Content type
application/json
{
  • "externalId": "string",
  • "name": "string",
  • "description": "string",
  • "dataSetId": 9007199254740991,
  • "rawTables": [
    • {
      }
    ],
  • "schedule": "string",
  • "contacts": [
    • {
      }
    ],
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    },
  • "source": "string",
  • "documentation": "string",
  • "notificationConfig": {
    • "allowedNotSeenRangeInMinutes": 0
    },
  • "createdBy": "string",
  • "id": 9007199254740991,
  • "lastSuccess": 0,
  • "lastFailure": 0,
  • "lastMessage": "string",
  • "lastSeen": 0,
  • "createdTime": 0,
  • "lastUpdatedTime": 0
}

Retrieve extraction pipelines

Retrieves information about multiple extraction pipelines in the same project. All ids and externalIds must be unique.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
required
Array of ExtPipeInternalId (object) or ExtPipeExternalId (object) (ExtPipeId) [ 1 .. 1000 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Update extraction pipelines

Update information for a list of extraction pipelines. Fields that are not included in the request, are not changed.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
required
Array of ExtPipeUpdateById (object) or ExtPipeUpdateByExternalId (object) (ExtPipeUpdate) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Extraction Pipelines Runs

Extraction Pipelines Runs are CDF objects to store statuses related to an extraction pipeline. The supported statuses are: success, failure and seen. The statuses are related to two different types of operation of the extraction pipeline. Success and failure indicate the status for a particular EP run where the EP attempts to send data to CDF. If the data is successfully posted to CDF the status of the run is ‘success’; if the run has been unsuccessful and the data is not posted to CDF, the status of the run is ‘failure’. Message can be stored to explain run status. Seen is a heartbeat status that indicates that the extraction pipeline is alive. This message is sent periodically on a schedule and indicates that the extraction pipeline is working even though data may not have been sent to CDF by the extraction pipeline.

Create extraction pipeline runs

Create multiple extraction pipeline runs. Current version supports one extraction pipeline run per request. Extraction pipeline runs support three statuses: success, failure, seen. The content of the Error Message parameter is configurable and will contain any messages that have been configured within the extraction pipeline.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
required
Array of objects (ExtPipeRunRequest) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Filter extraction pipeline runs

Use advanced filtering options to find extraction pipeline runs. Sorted by createdTime value with descendant order.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
required
object (RunsFilter)
limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Limits the number of results to return.

cursor
string

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "externalId": "string",
    • "statuses": [
      ],
    • "createdTime": {
      },
    • "message": {
      }
    },
  • "limit": 100,
  • "cursor": "string"
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

List extraction pipeline runs

List of all extraction pipeline runs for a given extraction pipeline. Sorted by createdTime value with descendant order.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
externalId
required
string
limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

Responses

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Extraction Pipelines Config

Extraction Pipelines Configs are configuration file revisions tied to an extraction pipeline. Users can create new configuration revisions, and extractors can fetch the latest, making it easy to deploy configuration files from source control, automated scripts, etc.

Create extraction configuration revision

Creates a configuration revision for the given extraction pipeline.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
externalId
required
string [ 1 .. 255 ] characters

External ID of the extraction pipeline this configuration revision belongs to.

config
string

Configuration content.

description
string or null

A description of this configuration revision.

Responses

Request samples

Content type
application/json
{
  • "externalId": "string",
  • "config": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "externalId": "string",
  • "config": "string",
  • "revision": 2147483647,
  • "createdTime": 0,
  • "description": "string"
}

Get a single configuration revision

Retrieves a single configuration revision. By default, the latest revision is retrieved.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
externalId
required
string
revision
integer <int32> >= 0
Default: 0
activeAtTime
integer <int64> >= 0
Default: 0

Responses

Response samples

Content type
application/json
{
  • "externalId": "string",
  • "config": "string",
  • "revision": 2147483647,
  • "createdTime": 0,
  • "description": "string"
}

List configuration revisions

Lists configuration revisions for the given extraction pipeline.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
externalId
required
string
limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

Responses

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Revert configuration revision

Reverts the latest configuration revision to an older revision. Equivalent to creating a new revision identical to the old revision.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
externalId
required
string [ 1 .. 255 ] characters

External ID of the extraction pipeline to revert configurations for.

revision
integer <int32> [ 0 .. 2147483647 ]

Revision number of this configuration.

Responses

Request samples

Content type
application/json
{
  • "externalId": "string",
  • "revision": 2147483647
}

Response samples

Content type
application/json
{
  • "externalId": "string",
  • "config": "string",
  • "revision": 2147483647,
  • "createdTime": 0,
  • "description": "string"
}

Data sets

Data sets let you document and track data lineage, ensure data integrity, and allow 3rd parties to write their insights securely back to a Cognite Data Fusion (CDF) project.

Data sets group and track data by its source. For example, a data set can contain all work orders originating from SAP. Typically, an organization will have one data set for each of its data ingestion pipelines in CDF.

A data set consists of metadata about the data set, and the data objects that belong to the data set. Data objects, for example events, files, and time series, are added to a data set through the dataSetId field of the data object. Each data object can belong to only one data set.

To learn more about data sets, see getting started guide

Aggregate data sets

Aggregate data sets in the same project. Criteria can be applied to select a subset of data sets.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
object (DataSetFilter)

Filter on data sets with strict matching.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "metadata": {
      },
    • "createdTime": {
      },
    • "lastUpdatedTime": {
      },
    • "externalIdPrefix": "my.known.prefix",
    • "writeProtected": true
    }
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Create data sets

You can create a maximum of 10 data sets per request.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of the data sets to create.

required
Array of objects (DataSetSpec) [ 1 .. 10 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Filter data sets

Use advanced filtering options to find data sets.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of IDs of the data sets to retrieve. You can retrieve a maximum of 1000 data sets per request. All IDs must be unique.

object (DataSetFilter)

Filter on data sets with strict matching.

limit
integer <int32> [ 1 .. 1000 ]
Default: 100

Limits the number of results to return.

cursor
string

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "metadata": {
      },
    • "createdTime": {
      },
    • "lastUpdatedTime": {
      },
    • "externalIdPrefix": "my.known.prefix",
    • "writeProtected": true
    },
  • "limit": 100,
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo"
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Retrieve data sets

Retrieve data sets by IDs or external IDs.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of the IDs of the data sets to retrieve. You can retrieve a maximum of 1000 data sets per request. All IDs must be unique.

required
Array of DataSetInternalId (object) or DataSetExternalId (object) (DataSetIdEither) [ 1 .. 1000 ] items unique
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Update data sets.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

All provided IDs and external IDs must be unique. Fields that are not included in the request, are not changed.

required
Array of DataSetChangeById (object) or DataSetChangeByExternalId (object) (DataSetUpdate)

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Labels

Create label definitions.

Creates label definitions that can be used across different resource types. The label definitions are uniquely identified by their external id.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of label definitions to create

required
Array of objects (ExternalLabelDefinition) [ 1 .. 1000 ] items unique

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete label definitions.

Delete all the label definitions specified by their external ids. The resource items that have the corresponding label attached remain unmodified. It is up to the client to clean up the resource items from their attached labels if necessary.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of external ids of label definitions to delete.

required
Array of objects (LabelDefinitionExternalId) [ 1 .. 1000 ] items unique

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{ }

Filter labels

Use advanced filtering options to find label definitions.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
object (Filter)

Filter on labels definitions with strict matching.

cursor
string
limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to return.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "name": "string",
    • "externalIdPrefix": "string",
    • "dataSetIds": [
      ]
    },
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
  • "limit": 100
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Relationships

The relationships resource type represents connections between resource objects in CDF. Relationships allow you to organize assets in other structures in addition to the standard hierarchical asset structure. Each relationship is between a source and a target object and is defined by a relationship type and the external IDs and resource types of the source and target objects. Optionally, a relationship can be time-constrained with a start and end time. To define and manage the available relationship types, use the labels resource type. The externalId field uniquely identifies each relationship.

Create relationships

List of the relationships to create. You can create a maximum of 1000 relationships per request. Relationships should be unique, but CDF does not prevent you from creating duplicates where only the externalId differs.

Relationships are uniquely identified by their externalId. Non-unique relationships will not be created.

The order of relationships in the response equals the order in the request.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Data required to create relationships. You can request a maximum of 1000 relationships per request.

required
Array of objects (relationship) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete relationships

Delete the relationships between resources identified by the external IDs in the request. You can delete a maximum of 1000 relationships per request.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Data required to delete relationships. You can delete a maximum of 1000 relationships per request.

required
Array of objects (itemsArray) [ 1 .. 1000 ] items
ignoreUnknownIds
boolean (ignoreUnknownIds)
Default: false

Ignore external IDs that are not found.

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{ }

Filter relationships

Lists relationships matching the query filter in the request. You can retrieve a maximum of 1000 relationships per request.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Data required to filter relationships. Combined filters are interpreted as an AND operation (not OR). Only relationships that match ALL the provided filters are returned.

object (advancedListFilter)

Filter on relationships with exact match. Multiple filter elements in one property, for example sourceExternalIds: [ "a", "b" ], returns all relationships where the sourceExternalId field is either aorb`. Filters in multiple properties return relationships that match all criteria. If the filter is not specified, it defaults to an empty filter.

limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to return.

cursor
string
fetchResources
boolean (fetchResources)
Default: false

If true, will try to fetch the resources referred to in the relationship, based on the users access rights. Will silently fail to attatch the resources if the user lacks access to some of them.

partition
string (Partition)

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.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "sourceExternalIds": [
      ],
    • "sourceTypes": [
      ],
    • "targetExternalIds": [
      ],
    • "targetTypes": [
      ],
    • "dataSetIds": [
      ],
    • "startTime": {
      },
    • "endTime": {
      },
    • "confidence": {
      },
    • "lastUpdatedTime": {
      },
    • "createdTime": {
      },
    • "activeAtTime": {
      },
    • "labels": {
      },
    • "sourcesOrTargets": [
      ]
    },
  • "limit": 100,
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
  • "fetchResources": false,
  • "partition": "1/10"
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

List relationships

Lists all relationships. The order of retrieved objects may change for two calls with the same parameters. The endpoint supports pagination. The initial call to this endpoint should not contain a cursor, but the cursor parameter should be used to retrieve further pages of results.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 100

Limits the number of results to be returned. The maximum results returned by the server is 1000 even if you specify a higher limit.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

partition
string
Example: partition=1/10

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.

Responses

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Retrieve relationships

Retrieve relationships by external IDs. You can retrieve a maximum of 1000 relationships per request. The order of the relationships in the response equals the order in the request.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Data required to list relationships.

required
Array of objects (itemsArray) [ 1 .. 1000 ] items
ignoreUnknownIds
boolean (ignoreUnknownIds)
Default: false

Ignore external IDs that are not found.

fetchResources
boolean (fetchResources)
Default: false

If true, will try to fetch the resources referred to in the relationship, based on the users access rights. Will silently fail to attatch the resources if the user lacks access to some of them.

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": false,
  • "fetchResources": false
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Update relationships

Update relationships between resources according to the partial definitions of the relationships given in the payload of the request. This means that fields not mentioned in the payload will remain unchanged. Up to 1000 relationships can be updated in one operation. To delete a value from an optional value the setNull field should be set to true. The order of the updated relationships in the response equals the order in the request.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Data required to update relationships.

required
Array of objects (relationshipUpdate) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Annotations

Annotations reflect contextual information in base CDF resource types, such as Files and Time series, that are not present on the object itself. The benefits of the annotations concept are threefold:

  • The annotations concept is a good fit for enriching the base resources themselves, so that the overall data quality is higher in a given project.
  • It is also a good fit for building reference datasets for data problems uniformly across customer projects. Product teams can then use those reference datasets to train machine learning models or validate the performance of their algorithms on actual customer data.
  • Given a uniform way of labelling similar concepts across projects, it becomes easy for apps to agree on a consistent visual representation of those concepts.

Create annotations

Creates the given annotations.

Identifiers

An annotation must reference an annotated resource.

The reference can be made by providing the internal ID of the annotated resource.

Status

The annotation must have the status field set to either "suggested", "rejected", or "approved"

Access control

The caller must have read-access on all the annotated resources, otherwise the call will fail.

Annotation types and Data

The annotation type property must be set to one of the globally available annotation types. See the documentation of the annotationType and data attributes for details.

The annotation data must conform to the schema provided by the annotation type.

Creating Application and User

The creating application and its version must be provided. The creating user must be provided, but if the annotation is being created by a service, this can be set to null.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

A request for creating annotations

required
Array of objects (AnnotationsV2CreateSchema) [ 1 .. 1000 ]

A list of annotations to create

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete annotations

Deletes the referenced annotations completely.

The caller must have read-access on all the annotated resources, otherwise the call will fail.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

A request referencing existing annotations

required
Array of objects (AnnotationsV2ReferenceSchema) [ 1 .. 1000 ]

A list of existing annotation references

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "error": {
    • "code": 401,
    • "message": "Could not authenticate.",
    • "missing": [
      ],
    • "duplicated": [
      ]
    }
}

Filter annotations

Lists the annotations the caller has access to, based on a filter.

The caller must have read-access on the annotated resources listed in the filter, otherwise the call will fail.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

A request specifying the annotation listing behavior

cursor
string or null [ 1 .. 255 ] characters

A cursor pointing to another page of results

limit
integer [ 1 .. 1000 ]
Default: 25
required
object (AnnotationsV2FilterSchema)

A filter to apply on annotations

Responses

Request samples

Content type
application/json
{
  • "cursor": "MzE1NjAwMDcxNzQ0ODI5",
  • "limit": 25,
  • "filter": {
    • "annotatedResourceType": "file",
    • "annotatedResourceIds": [
      ],
    • "status": "approved",
    • "data": {
      }
    }
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": null
}

Get an annotation

Retrieves the referenced annotation.

The caller must have read-access on the annotated resource, otherwise the call will fail.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
annotationId
required
integer <int64> (AnnotationId) [ 1 .. 9007199254740991 ]
Example: 4096

The internal ID of the annotation

Responses

Response samples

Content type
application/json
{
  • "id": 4096,
  • "createdTime": 0,
  • "lastUpdatedTime": 0,
  • "annotatedResourceType": "file",
  • "annotatedResourceId": 1337,
  • "annotationType": "images.ObjectDetection",
  • "creatingApp": "cognite-vision",
  • "creatingAppVersion": "1.2.1",
  • "creatingUser": "john.doe@cognite.com",
  • "data": {
    • "assetRef": {
      },
    • "symbolRegion": {
      },
    • "textRegion": {
      },
    • "pageNumber": 43
    },
  • "status": "approved"
}

Retrieve annotations

Retrieves the referenced annotations.

The caller must have read-access on all the annotated resources, otherwise the call will fail.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

A request referencing existing annotations

required
Array of objects (AnnotationsV2ReferenceSchema) [ 1 .. 1000 ]

A list of existing annotation references

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Suggest annotations

Suggests the given annotations, i.e. creates them with status set to "suggested"

Identifiers

An annotation must reference an annotated resource.

The reference can be made by providing the internal ID of the annotated resource.

Access control

The caller must have read-access on all the annotated resources, otherwise the call will fail.

Annotation types and Data

The annotation type property must be set to one of the globally available annotation types. See the documentation of the annotationType and data attributes for details.

The annotation data must conform to the schema provided by the annotation type.

Creating Application and User

The creating application and its version must be provided. The creating user must be provided, but if the annotation is being created by a service, this can be set to null.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

A request for suggesting annotations, i.e., creating them with the "suggested" status

required
Array of objects (AnnotationsV2SuggestSchema) [ 1 .. 1000 ]

A list of annotations to suggest

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Update annotations

Updates the referenced annotations.

The caller must have read-access on all the annotated resources, otherwise the call will fail.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

A request for updating existing annotations

required
Array of objects (AnnotationsV2UpdateItemSchema) [ 1 .. 1000 ]

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Vectorstore

INTERNAL documentation

The Vectorstore service allows you to store and retrieve data objects, based on their semantic properties by indexing them with vectors.

Before inserting or querying data, you need to create a namespace. This namespace configuration is then used by the service to determine vector embeddings, access control, etc.

A general use case can look like:

  1. Create a namespace
  2. Insert text chunks into the namespace
  3. Query the namespace for similar text chunks

Transformations

Transformations enable users to use Spark SQL queries to transform data from the CDF staging area, RAW, into the CDF data model.

Cancel a transformation

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

Request Body schema: application/json
One of
externalId
required
string

The external ID provided by the client. Must be unique for the resource type.

Responses

Request samples

Content type
application/json
Example
{
  • "externalId": "string"
}

Response samples

Content type
application/json
{ }

Create transformations

Create a maximum of 1000 transformations per request.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

Request Body schema: application/json
Array of objects (TransformationCreate) <= 1000 items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete transformations

Delete a maximum of 1000 transformations by ids and externalIds per request.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

Request Body schema: application/json
Array of TransformationCogniteExternalId (object) or TransformationCogniteInternalId (object) <= 1000 items
ignoreUnknownIds
boolean

Ignore IDs and external IDs that are not found. Defaults to false.

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": true
}

Response samples

Content type
application/json
{ }

Filter transformations

Filter transformations. Use nextCursor to paginate through the results.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

Request Body schema: application/json
required
object (TransformationFilter)
limit
integer <int32>
cursor
string

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "isPublic": true,
    • "nameRegex": "string",
    • "queryRegex": "string",
    • "destinationType": "string",
    • "conflictMode": "abort",
    • "hasBlockedError": true,
    • "cdfProjectName": "string",
    • "createdTime": {
      },
    • "lastUpdatedTime": {
      },
    • "dataSetIds": [
      ],
    • "tags": {
      }
    },
  • "limit": 0,
  • "cursor": "string"
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

List transformations

List transformations. Use nextCursor to paginate through the results.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

query Parameters
limit
integer <int32> [ 1 .. 1000 ]

Limits the number of results to be returned. The maximum is 1000, default limit is 100.

cursor
string

Cursor for paging through results.

includePublic
boolean

Whether public transformations should be included in the results. The default is true.

withJobDetails
boolean

Whether transformations should contain information about jobs. The default is true.

Responses

Request samples

transformations_list = client.transformations.list()

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Retrieve transformations

Retrieve a maximum of 1000 transformations by ids and externalIds per request.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

Request Body schema: application/json
Array of TransformationCogniteExternalId (object) or TransformationCogniteInternalId (object) <= 1000 items
ignoreUnknownIds
boolean

Ignore IDs and external IDs that are not found. Defaults to false.

withJobDetails
required
boolean

Whether the transformations will be returned with running job and last created job details.

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": true,
  • "withJobDetails": true
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Run a transformation

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

Request Body schema: application/json
One of
externalId
required
string
object (NonceCredentials)

Responses

Request samples

Content type
application/json
Example
{
  • "externalId": "string",
  • "nonce": {
    • "sessionId": 0,
    • "nonce": "string",
    • "cdfProjectName": "string",
    • "clientId": "string"
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "uuid": "string",
  • "transformationId": 0,
  • "transformationExternalId": "string",
  • "sourceProject": "string",
  • "destinationProject": "string",
  • "destination": {
    • "type": "assets"
    },
  • "conflictMode": "abort",
  • "query": "string",
  • "createdTime": 0,
  • "startedTime": 0,
  • "finishedTime": 0,
  • "lastSeenTime": 0,
  • "error": "string",
  • "ignoreNullFields": true,
  • "status": "Completed"
}

Update transformations

Update the attributes of transformations, maximum 1000 per request.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

Request Body schema: application/json
Array of UpdateItemWithExternalId_TransformationUpdate (object) or UpdateItemWithId_TransformationUpdate (object) <= 1000 items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Transformation Jobs

Transformation jobs let you execute transformations asynchronously.

List job metrics by job id

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

id
required
integer <int32>

The job id.

Responses

Request samples

res = client.transformations.jobs.list_metrics(id=1)

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

List jobs

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

query Parameters
transformationId
integer <int32>

List only jobs for the specified transformation. The transformation is identified by ID.

transformationExternalId
string

List only jobs for the specified transformation. The transformation is identified by external ID.

limit
integer <int32> [ 1 .. 1000 ]

Limits the number of results to be returned. The maximum is 1000, default limit is 100.

cursor
string

Cursor for paging through results.

Responses

Request samples

transformation_jobs_list = client.transformations.jobs.list()

transformation_jobs_list = client.transformations.jobs.list(transformation_id = 1)

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Retrieve jobs by ids

Retrieve a maximum of 1000 jobs by ids per request.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

Request Body schema: application/json
Array of objects (TransformationCogniteInternalId)
ignoreUnknownIds
boolean

Ignore IDs and external IDs that are not found. Defaults to false.

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": true
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Transformation Schedules

Transformation schedules allow you to run transformations with a specific input at intervals defined by a cron expression. These transformation jobs will be asynchronous and show up in the transformation job list. Visit http://www.cronmaker.com to generate a cron expression with a UI.

List all schedules

List all transformation schedules. Use nextCursor to paginate through the results.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

query Parameters
limit
integer <int32> [ 1 .. 1000 ]

Limits the number of results to be returned. The maximum is 1000, default limit is 100.

cursor
string

Cursor for paging through results.

includePublic
boolean

Whether public transformations should be included in the results. The default is true.

Responses

Request samples

schedules_list = client.transformations.schedules.list()

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Retrieve schedules

Retrieve transformation schedules by transformation IDs or external IDs.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

Request Body schema: application/json

List of transformation IDs of schedules to retrieve. Must be up to a maximum of 1000 items and all of them must be unique.

Array of TransformationCogniteExternalId (object) or TransformationCogniteInternalId (object) <= 1000 items
ignoreUnknownIds
boolean

Ignore IDs and external IDs that are not found. Defaults to false.

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": true
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Schedule transformations

Schedule transformations with the specified configurations.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

Request Body schema: application/json

List of the schedules to create. Must be up to a maximum of 1000 items.

Array of ScheduleParametersWithExternalId (object) or ScheduleParametersWithId (object)

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Unschedule transformations

Unschedule transformations by IDs or externalIds.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

Request Body schema: application/json

List of transformation IDs of schedules to delete. Must be up to a maximum of 1000 items and all of them must be unique.

Array of TransformationCogniteExternalId (object) or TransformationCogniteInternalId (object) <= 1000 items
ignoreUnknownIds
boolean

Ignore IDs and external IDs that are not found. Defaults to false.

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": true
}

Response samples

Content type
application/json
{ }

Update schedules

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

Request Body schema: application/json

List of schedule updates. Must be up to a maximum of 1000 items.

Array of UpdateItemWithExternalId_ScheduleUpdate (object) or UpdateItemWithId_ScheduleUpdate (object)

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Transformation Notifications

Transformation notifications let users know when a job fails if subscribed.

Delete notification subscriptions by notification ID

Deletes the specified notification subscriptions on the transformation. Requests to delete non-existing subscriptions do nothing, but do not throw an error.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

Request Body schema: application/json

List of IDs to be deleted.

Array of objects (TransformationCogniteInternalId)

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{ }

List notification subscriptions

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

query Parameters
transformationId
integer <int32>

List only notifications for the specified transformation. The transformation is identified by ID.

transformationExternalId
string

List only notifications for the specified transformation. The transformation is identified by external ID.

destination
string

Filter by notification destination.

limit
integer <int32> [ 1 .. 1000 ]

Limits the number of results to be returned. The maximum is 1000, default limit is 100.

cursor
string

Cursor for paging through results.

Responses

Request samples

notifications_list = client.transformations.notifications.list()

notifications_list = client.transformations.notifications.list(transformation_id = 1)

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Subscribe for notifications

Subscribe for notifications on the transformation errors.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

Request Body schema: application/json

List of the notifications for new subscriptions. Must be up to a maximum of 1000 items.

Array of NotificationCreateWithExternalId (object) or NotificationCreateWithId (object) <= 1000 items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Query

Query lets the users preview the result of their queries.

Run query

Preview a SQL query.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

Request Body schema: application/json
query
required
string

SQL query to run for preview.

convertToString
required
boolean

Stringify values in the query results.

limit
integer <int32>

End-result limit of the query.

sourceLimit
integer <int32>

Limit for how many rows to download from the data sources.

inferSchemaLimit
integer <int32>

Limit for how many rows that are used for inferring schema. Default is 10,000.

timeout
integer <int32>

Number of seconds to wait before cancelling a query. The default, and maximum, is 240.

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "convertToString": true,
  • "limit": 0,
  • "sourceLimit": 0,
  • "inferSchemaLimit": 0,
  • "timeout": 0
}

Response samples

Content type
application/json
{
  • "schema": {
    • "items": [
      ]
    },
  • "results": {
    • "items": [
      ]
    }
}

Schema

Schema provides the expected schema for CDF resources.

Get Instance schema.

For View centric schema, viewSpace, viewExternalId, viewVersion need to be specified while withInstanceSpace, isConnectionDefinition, instanceType are optional . For Data Model centric schema, dataModelSpace, dataModelExternalId, dataModelVersion, type need to be specified and relationshipFromType is optional. For Both scenarios conflictMode is required.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

query Parameters
conflictMode
string
Enum: "abort" "upsert" "update" "delete"

conflict mode of the transformation. One of the following conflictMode types can be provided: upsert, delete

viewSpace
string non-empty

Space of the View. Not required if isConnectionDefinition is true. Relevant for View centric schema.

viewExternalId
string non-empty

External id of the View. Not required if isConnectionDefinition is true. Relevant for View centric schema.

viewVersion
string non-empty

Version of the View. Not required if isConnectionDefinition is true. Relevant for View centric schema.

instanceType
string
Enum: "nodes" "edges"

Instance type to deal with

withInstanceSpace
boolean

Is instance space set at the transformation config or not

isConnectionDefinition
boolean

If the edge is a connection definition or not

dataModelSpace
string non-empty

Space of the Data Model. Relevant for Data Model centric schema.

dataModelExternalId
string non-empty

External id of the Data Model. Relevant for Data Model centric schema.

dataModelVersion
string non-empty

Version of the Data Model. Relevant for Data Model centric schema.

type
string non-empty

External id of the View in the Data model. Relevant for Data Model centric schema.

relationshipFromType
string non-empty

Property Identifier of Connection Definition in type. Relevant for Data Model centric schema.

Responses

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Get the schema of a sequence

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

query Parameters
externalId
required
string non-empty

External ID of the Sequence

Responses

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Get the schema of resource type

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
project
required
string

The project name.

schemaType
required
string

Name of the target schema type, please provide one of the following: assets, timeseries, asset_hierarchy, events, datapoints string_datapoints, sequences, files, labels, relationships, raw, data_sets

query Parameters
conflictMode
string

One of the following conflictMode types can be provided: abort, upsert, update, delete

Responses

Request samples

from cognite.client.data_classes import TransformationDestination
columns = client.transformations.schema.retrieve(destination = TransformationDestination.assets())

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Functions

Functions enables Python code to be hosted and executed in the cloud, on demand or by using a schedule. Execution, status and logs are available through the API. A function is uploaded to the Files API as a zip file with at least a Python file called handler.py (unless specified otherwise through the functionPath-argument) that must contain a function named handle with any of the following arguments: data, client, secrets, or 'function_call_info', which are passed into the function. The latest version of Cognite SDK's are available, and additional python packages and version specifications can be defined in a requirements.txt in the root of the zip.

Activate Functions

Activate Cognite Functions. This will create the necessary backend infrastructure for Cognite Functions.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code

Responses

Request samples

status = client.functions.activate()

Response samples

Content type
application/json
{
  • "status": "inactive"
}

Create functions

You can only create one function per request.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
required
Array of objects (Function) = 1 items

Array of functions to create.

Responses

Request samples

Content type
application/json
Example
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete functions

Delete functions. You can delete a maximum of 10 functions per request. Function source files stored in the Files API must be deleted separately.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
required
Array of FunctionId (object) or FunctionExternalId (object) (FunctionIdEither) [ 1 .. 10 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{ }

Filter functions

Use advanced filtering options to find functions.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
object (FunctionFilter)
limit
integer <int32> >= 1
Default: 100

Limits the number of results to be returned.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "status": "Queued",
    • "createdTime": {
      }
    }
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Functions limits

Service limits for the associated project.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code

Responses

Request samples

limits = client.functions.limits()

Response samples

Content type
application/json
{
  • "timeoutMinutes": 15,
  • "cpuCores": {
    • "min": 0.1,
    • "max": 0.6,
    • "default": 0.25
    },
  • "memoryGb": {
    • "min": 0.1,
    • "max": 2.5,
    • "default": 1
    },
  • "runtimes": [
    • "py38",
    • "py39",
    • "py310"
    ],
  • "responseSizeMb": 1
}

Get activation status

Get activation status

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code

Responses

Request samples

status = client.functions.status()

Response samples

Content type
application/json
{
  • "status": "inactive"
}

List functions

List functions.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
limit
integer >= 1
Default: 100

Limits the number of results to be returned.

Responses

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Retrieve a function by its id

Retrieve a function by its id. If you want to retrieve functions by names, use Retrieve functions instead.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
functionId
required
integer

The function id.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "createdTime": 123455234,
  • "status": "Queued",
  • "name": "myfunction",
  • "externalId": "my.known.id",
  • "fileId": 1,
  • "owner": "user@cognite.com",
  • "description": "My fantastic function with advanced ML",
  • "metadata": {
    • "property1": "string",
    • "property2": "string"
    },
  • "secrets": {
    • "MySecret": "***"
    },
  • "functionPath": "myfunction/handler.py",
  • "envVars": {
    • "MyKey": "MyValue"
    },
  • "cpu": 0.25,
  • "memory": 1,
  • "runtime": "py38",
  • "runtimeVersion": "Python 3.8.13",
  • "error": {
    • "code": 400,
    • "message": "Could not build function."
    }
}

Retrieve functions

Retrieve functions by ids.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
required
Array of FunctionId (object) or FunctionExternalId (object) (FunctionIdEither) [ 1 .. 10 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Function calls

Function calls let you execute functions asynchronously with a timeout of 15 minutes.

Call a function asynchronously

Perform a function call. To provide input data to the function, add the data in an object called data in the request body. It will be available as the data argument into the function. Info about the function call at runtime can be obtained through the function_call_info argument if added in the function handle. WARNING: Secrets or other confidential information should not be passed via the data object. There is a dedicated secrets object in the request body to "Create functions" for this purpose.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
functionId
required
integer

The function id.

Request Body schema: application/json
data
object (data)

Input data to the function (only present if provided on the schedule). This data is passed deserialized into the function through one of the arguments called data. WARNING: Secrets or other confidential information should not be passed via the data object. There is a dedicated secrets object in the request body to "Create functions" for this purpose.'

nonce
string (nonce)

Nonce retrieved from sessions API when creating a session. This will be used to bind the session before executing the function. The corresponding access token will be passed to the function and used to instantiate the client of the handle() function. You can create a session via the Sessions API. When using the Python SDK, the session will be created behind the scenes when creating the schedule.

Responses

Request samples

Content type
application/json
{
  • "data": {
    • "timeSeriesId1": 13435351,
    • "maxValue": 4
    },
  • "nonce": "string"
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "status": "Running",
  • "startTime": 0,
  • "endTime": 0,
  • "error": {
    • "trace": "Cannot assign foo to bar.",
    • "message": "Could not authenticate."
    },
  • "scheduleId": 1,
  • "functionId": 1,
  • "scheduledTime": 0
}

Filter function calls

Use advanced filtering options to find function calls.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
functionId
required
integer

The function id.

Request Body schema: application/json
object (FunctionCallFilter)
limit
integer <int32> >= 1
Default: 100

Limits the number of results to be returned.

cursor
string

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "status": "Running",
    • "scheduleId": 123,
    • "startTime": {
      }
    },
  • "limit": 10
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

List function calls

List function calls.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
functionId
required
integer

The function id.

query Parameters
limit
integer >= 1
Default: 100

Limits the number of results to be returned.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

Responses

Request samples

logs = client.functions.calls.get_logs(call_id=2, function_id=1)

call = client.functions.calls.retrieve(call_id=2, function_id=1)
logs = call.get_logs()

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Retrieve a function call by its id

Retrieve function calls.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
callId
required
integer

The function call id.

functionId
required
integer

The function id.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "status": "Running",
  • "startTime": 0,
  • "endTime": 0,
  • "error": {
    • "trace": "Cannot assign foo to bar.",
    • "message": "Could not authenticate."
    },
  • "scheduleId": 1,
  • "functionId": 1,
  • "scheduledTime": 0
}

Retrieve calls

Retrieve function calls by call ids.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
functionId
required
integer

The function id.

Request Body schema: application/json

List of IDs of calls to retrieve. Must be up to a maximum of 10000 items and all of them must be unique.

required
Array of objects (FunctionCallId) [ 1 .. 10000 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Retrieve logs for function call

Get logs from a function call.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
callId
required
integer

The function call id.

functionId
required
integer

The function id.

Responses

Response samples

Content type
application/json
{
  • "items": [
    • {
      },
    • {
      }
    ]
}

Retrieve response for function call

Retrieve response from a function call.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
callId
required
integer

The function call id.

functionId
required
integer

The function id.

Responses

Request samples

response = client.functions.calls.get_response(call_id=2, function_id=1)

call = client.functions.calls.retrieve(call_id=2, function_id=1)
response = call.get_response()

Response samples

Content type
application/json
{
  • "response": {
    • "numAssets": 1234,
    • "someCalculation": 3.14
    }
}

Function schedules

Function schedules allow you to run functions with a specific input at intervals defined by a cron expression. These function calls will be asynchronous and show up in the function call list. Visit http://www.cronmaker.com to generate a cron expression with a UI.

Create schedules

Create function schedules. Function schedules trigger asynchronous calls with specific input data, based on a cron expression that determines when these triggers should be fired. Use e.g. http://www.cronmaker.com to be guided on how to generate a cron expression. One of FunctionId or FunctionExternalId (deprecated) must be set (but not both). When creating a schedule with a session, i.e. with a nonce, FunctionId must be used. The nonce will be used to bind the session before function execution, and the session will be kept alive for the lifetime of the schedule. WARNING: Secrets or other confidential information should not be passed via the data object. There is a dedicated secrets object in the request body to "Create functions" for this purpose.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
required
Array of objects (FunctionSchedule) = 1 items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete schedules

Delete function schedules.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
required
Array of objects (FunctionScheduleId) [ 1 .. 10000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{ }

Filter function schedules

Use advanced filtering options to find function schedules. At most one of FunctionId or FunctionExternalId can be specified.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
object (FunctionScheduleFilter)
limit
integer <int32> >= 1
Default: 100

Limits the number of results to be returned.

Responses

Request samples

Content type
application/json
{
  • "filter": {
    • "name": "MySchedule",
    • "cronExpression": "5 4 * * *"
    }
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

List schedules

List function schedules in project.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
limit
integer >= 1
Default: 100

Limits the number of results to be returned.

Responses

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Retrieve a function schedule by its id

Retrieve a function schedule by its id.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
scheduleId
required
integer

The function schedule id.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "name": "My schedule",
  • "createdTime": 0,
  • "description": "This is a nice schedule",
  • "cronExpression": "* * * * *",
  • "when": "Every hour",
  • "functionId": 1,
  • "functionExternalId": "my.known.id",
  • "sessionId": "string"
}

Retrieve function input data

Retrieve the input data to the associated function.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
path Parameters
scheduleId
required
integer

The function schedule id.

Responses

Request samples

client.functions.schedules.get_input_data(id=123)

Response samples

Content type
application/json
{
  • "id": 1,
  • "data": {
    • "timeSeriesId1": 13435351,
    • "maxValue": 4
    }
}

Retrieve schedules

Retrieve function schedules by schedule ids.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of IDs of schedules to retrieve. Must be up to a maximum of 10000 items and all of them must be unique.

required
Array of objects [ 1 .. 10000 ] items
ignoreUnknownIds
boolean
Default: false

Ignore IDs and external IDs that are not found

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "ignoreUnknownIds": false
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Data Modeling

Use the Data Model Storage API to manage your data in CDF.

You define a data model with views and data containers. Data containers specify how the service stores data.
Views define the logical view of the stored data. Nodes and edges are representations of data containers. We call these node and edge representations "instances". Each node or edge can hold one or more data containers. You can query nodes and edges using views. Views combine data from one or more data containers.

A container represents a bag of properties. These properties have a type. They also have optional constraints, default values, and you can choose to index them.

Each data container has a default view available so you can query all its properties.

A data model is a collection (set) of views. Use the data model to group and structure views into a recognizable, and understood model. The model represents a reusable collection of data.

Each data model has a version. A data model can also import other data models, so you can reuse views.

All resources described have to belong to a space. You use a space to create a logical grouping of your resources, and to act as a governance boundary. A space defines a namespace.

You use the space (name) and the external-id - externalId - for the resource to identify it. For view or container properties, the external-id for the view - or container - is part of the identifier. This means you can have resources using the exact external-id in two different spaces.

Data models

Create or update data models

Add or update (upsert) data models. For unchanged data model specifications, the operation completes without making any changes. We will not update the lastUpdatedTime value for models that remain unchanged.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of data models to add

required
Array of objects (DataModelCreate) [ 1 .. 100 ] items

List of data models to create/update

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete data models

Delete one or more data models. Currently limited to 100 models at a time. This does not delete the views, nor the containers they reference.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of references to data models you wish to delete

required
Array of objects [ 1 .. 100 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Filter data models

List data models in a project when they match a given filter.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Filter based on name, externalIds, versions and space. It also supports sorting and pagination.

cursor
string
limit
integer [ 1 .. 1000 ]
Default: 10
spaces
Array of strings (SpaceSpecification) [ items [ 1 .. 43 ] characters ^[a-zA-Z][a-zA-Z0-9_-]{0,41}[a-zA-Z0-9]?$ ]

List of spaces you want to use to limit the returned matches by

(BoolFilter (and (object) or or (object) or not (object))) or (LeafFilter (equals (object) or in (object) or range (object) or prefix (object) or exists (object) or containsAny (object) or containsAll (object) or matchAll (object) or nested (object) or overlaps (object) or hasData (object))) (FilterDefinition)

A filter Domain Specific Language (DSL) used to create advanced filter queries.

allVersions
boolean (AllVersionsFlag)
Default: false

If all versions of the entity should be returned. Defaults to false which returns the latest version, attributed to the newest 'createdTime' field

includeGlobal
boolean (IncludeGlobalFlag)
Default: false

If the global items of the entity should be returned. Defaults to false which excludes global items.

Responses

Request samples

Content type
application/json
{
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
  • "limit": 10,
  • "spaces": [
    • "string"
    ],
  • "filter": {
    • "and": [
      ]
    },
  • "allVersions": false,
  • "includeGlobal": false
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

List data models defined in the project

List data models defined in the project. You can filter the returned models by the specified space.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 10

Limit the number of results returned. The largest result-set returned by the server will be 1000 items, even if you specify a higher limit.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

inlineViews
boolean
Default: false

Should we expand the referenced views inline in the returned result.

space
string [ 1 .. 43 ] characters ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,41}[a-zA-Z0-9]?$
Example: space=timeseries

The space to query.

allVersions
boolean
Default: false

If all versions of the entity should be returned. Defaults to false which returns the latest version, attributed to the newest 'createdTime' field

includeGlobal
boolean
Default: false

If the global items of the entity should be returned. Defaults to false which excludes global items.

Responses

Request samples

data_model_list = client.data_modeling.data_models.list(limit=5)

for data_model in client.data_modeling.data_models:
    data_model # do something with the data_model

for data_model_list in client.data_modeling.data_models(chunk_size=10):
    data_model_list # do something with the data model

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Retrieve data models by their external ids

Retrieve up to 100 data models by their external ids. Views can be auto-expanded when the InlineViews query parameter is set.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
inlineViews
boolean
Default: false

Should we expand the referenced views inline in the returned result.

Request Body schema: application/json

List of external-ids of data models to retrieve.

required
Array of objects [ 1 .. 100 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Spaces

Create or update spaces

Add or update (upsert) spaces. For unchanged space specifications, the operation completes without making any changes. We will not update the lastUpdatedTime value for spaces that remain unchanged.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Spaces to add or update.

required
Array of objects (SpaceCreateDefinition) [ 1 .. 100 ] items

List of spaces to create/update

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete spaces

Delete one or more spaces. Currently limited to 100 spaces at a time.

If an existing data model references a space, you cannot delete that space. Nodes, edges and other data types that are part of a space will no longer be available.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of space-ids for spaces to delete.

required
Array of objects [ 1 .. 100 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

List spaces defined in the project

List spaces defined in the current project.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 10

Limit the number of results returned. The largest result-set returned by the server will be 1000 items, even if you specify a higher limit.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

includeGlobal
boolean
Default: false

If the global items of the entity should be returned. Defaults to false which excludes global items.

Responses

Request samples

space_list = client.data_modeling.spaces.list(limit=5)

for space in client.data_modeling.spaces:
    space # do something with the space

for space_list in client.data_modeling.spaces(chunk_size=2500):
    space_list # do something with the spaces

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Retrieve spaces by their space-ids

Retrieve up to 100 spaces by specifying their space-ids.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of space-ids for the spaces to return.

required
Array of objects [ 1 .. 100 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Views

Create or update views

Add or update (upsert) views. For unchanged view specifications, the operation completes without making any changes. We will not update the lastUpdatedTime value for views that remain unchanged.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Views to add or update.

required
Array of objects (ViewCreateDefinition) [ 1 .. 100 ] items

List of views to create/update

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete views

Delete one or more views. Currently limited to 100 views at a time. The service cannot delete a view referenced by a data model.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of references to views you want to delete.

required
Array of objects [ 1 .. 100 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

List views defined in the project

List of views defined in the current project. You can filter the list by specifying a space.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 10

Limit the number of results returned. The largest result-set returned by the server will be 1000 items, even if you specify a higher limit.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

space
string [ 1 .. 43 ] characters ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,41}[a-zA-Z0-9]?$
Example: space=timeseries

The space to query.

includeInheritedProperties
boolean
Default: true

Include properties inherited from views this view implements.

allVersions
boolean
Default: false

If all versions of the entity should be returned. Defaults to false which returns the latest version, attributed to the newest 'createdTime' field

includeGlobal
boolean
Default: false

If the global items of the entity should be returned. Defaults to false which excludes global items.

Responses

Request samples

view_list = client.data_modeling.views.list(limit=5)

for view in client.data_modeling.views:
    view # do something with the view

for view_list in client.data_modeling.views(chunk_size=10):
    view_list # do something with the views

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Retrieve views by their external ids

Retrieve up to 100 views by their external ids.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
includeInheritedProperties
boolean
Default: true

Include properties inherited from views this view implements.

Request Body schema: application/json

List of external-ids of views to retrieve.

required
Array of objects [ 1 .. 100 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Containers

Create or update containers

Add or update (upsert) containers. For unchanged container specifications, the operation completes without making any changes. We will not update the lastUpdatedTime value for containers that remain unchanged.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Containers to add or update.

required
Array of objects (ContainerCreateDefinition) [ 1 .. 100 ] items

List of containers to create/update

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete constraints from containers

Delete one or more container constraints. Currently limited to 10 constraints at a time.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of the references to constraints you want to delete.

required
Array of objects [ 1 .. 10 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete containers

Delete one or more containers. Currently limited to 100 containers at a time. You cannot delete a container when one or more data model(s) or view(s) references it.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of the spaces and external-ids for the containers you want to delete.

required
Array of objects [ 1 .. 100 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete indexes from containers

Delete one or more container indexes. Currently limited to 10 indexes at a time.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of the references to indexes you want to delete.

required
Array of objects [ 1 .. 10 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

List containers defined in the project

List of containers defined in the current project. You can filter the list by specifying a space.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 10

Limit the number of results returned. The largest result-set returned by the server will be 1000 items, even if you specify a higher limit.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

space
string [ 1 .. 43 ] characters ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,41}[a-zA-Z0-9]?$
Example: space=timeseries

The space to query.

includeGlobal
boolean
Default: false

If the global items of the entity should be returned. Defaults to false which excludes global items.

Responses

Request samples

container_list = client.data_modeling.containers.list(limit=5)

for container in client.data_modeling.containers:
    container # do something with the container

for container_list in client.data_modeling.containers(chunk_size=10):
    container_list # do something with the containers

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}

Retrieve containers by their external ids

Retrieve up to 100 containers by their specified external ids.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of external-ids of containers to retrieve.

required
Array of objects [ 1 .. 100 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Instances

Aggregate data across nodes/edges

Aggregate data for nodes or edges in a project. You can use an optional query or filter specification to limit the result.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Aggregation specification.

One of
query
string

Optional query string. The API will parse the query string, and use it to match the text properties on elements to use for the aggregate(s).

properties
Array of strings [ 1 .. 200 ] items

Optional list (array) of properties you want to apply the query above to. If you do not list any properties, you search through text fields by default.

limit
integer [ 1 .. 1000 ]
Default: 100

Limit the number of results returned. The default limit is currently at 100 items.

Array of avg (object) or count (object) or min (object) or max (object) or sum (object) or histogram (object) (AggregationDefinition) <= 5 items
groupBy
Array of strings [ 1 .. 5 ] items

The selection of fields to group the results by when doing aggregations. You can specify up to 5 items to group by.

When you do not specify any aggregates, the fields listed in the groupBy clause will return the unique values stored for each field.

(BoolFilter (and (object) or or (object) or not (object))) or (LeafFilter (equals (object) or in (object) or range (object) or prefix (object) or exists (object) or containsAny (object) or containsAll (object) or matchAll (object) or nested (object) or overlaps (object) or hasData (object))) (FilterDefinition)

A filter Domain Specific Language (DSL) used to create advanced filter queries.

instanceType
string (InstanceType)
Default: "node"
Enum: "node" "edge"

The type of instance

required
object (ViewReference)

Reference to a view

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "properties": [
    • "string"
    ],
  • "limit": 100,
  • "aggregates": [
    • {
      }
    ],
  • "groupBy": [
    • "string"
    ],
  • "filter": {
    • "and": [
      ]
    },
  • "instanceType": "node",
  • "view": {
    • "type": "view",
    • "space": "string",
    • "externalId": "string",
    • "version": "string"
    }
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "typing": {
    • "property-identifier1": {
      },
    • "property-identifier2": {
      }
    }
}

Create or update nodes/edges

Create or update nodes and edges in a transaction. The items field of the payload is an array of objects where each object describes a node or an edge to create, patch or replace. The instanceType field of each object must be node or edge and determines how the rest of the object is interpreted.

This operation is currently limited to 1000 nodes and/or edges at a time.

Individual nodes and edges are uniquely identified by their externalId and space.

Creating new instances

When there is no node or edge with the given externalId in the given space, a node will be created and the properties provided for each of the containers or views in the sources array will be populated for the node/edge. Nodes can also be created implicitly when an edge between them is created (if autoCreateStartNodes and/or autoCreateEndNodes is set), or when a direct relation property is set, the target node does not exist and autoCreateDirectRelations is set.

To add a node or edge, the user must have capabilities to access (write to) both the view(s) referenced in sources and the container(s) underlying these views, as well as any directly referenced containers.

Updating (patching) or replacing instances

When a node or edge (instance) with the given externalId already exists in a space, the properties named in the sources field will be written to the instance. Other properties will remain unchanged. To replace the whole set of properties for an instance (a node or an edge) rather than patch the instance, set the replace parameter to true.

If you use a writable view to update properties (that is, the source you are referring to in sources is a view), you must have write access to the view as well as all of its backing containers.

No-change patch operations

When a node/edge item has no changes compared to the existing instance - that is, when the supplied property values are equal to the corresponding values in the existing node/edge, the node/edge will stay unchanged. In this case, the lastUpdatedTime values for the nodes/edges in question will not change.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Nodes/edges to add or update.

required
Array of NodeWrite (object) or EdgeWrite (object) (NodeOrEdgeCreate) [ 1 .. 1000 ] items

List of nodes and edges to create/update

autoCreateDirectRelations
boolean
Default: true

Should we create missing target nodes of direct relations? If the target-container constraint has been specified for a direct relation, the target node cannot be auto-created. If you want to point direct relations to a space where you have only read access, this option must be set to false.

autoCreateStartNodes
boolean
Default: false

Should we create missing start nodes for edges when ingesting? By default, the start node of an edge must exist before we can ingest the edge.

autoCreateEndNodes
boolean
Default: false

Should we create missing end nodes for edges when ingesting? By default, the end node of an edge must exist before we can ingest the edge.

skipOnVersionConflict
boolean
Default: false

If existingVersion is specified on any of the nodes/edges in the input, the default behaviour is that the entire ingestion will fail when version conflicts occur. If skipOnVersionConflict is set to true, items with version conflicts will be skipped instead. If no version is specified for nodes/edges, it will do the write directly.

replace
boolean
Default: false

How do we behave when a property value exists? Do we replace all matching and existing values with the supplied values (true)? Or should we merge in new values for properties together with the existing values (false)? Note: This setting applies for all nodes or edges specified in the ingestion call.

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "autoCreateDirectRelations": true,
  • "autoCreateStartNodes": false,
  • "autoCreateEndNodes": false,
  • "skipOnVersionConflict": false,
  • "replace": false
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Delete nodes/edges

Delete nodes and edges in a transaction. Limited to 1000 nodes/edges at a time.

When a node is selected for deletion, all connected incoming and outgoing edges that point to or from it are also deleted. However, please note that the operation might fail if the node has a high number of edge connections. If this is the case, consider deleting the edges connected to the node before deleting the node itself.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of types, spaces, and external-ids for nodes and edges to delete.

required
Array of objects [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Filter nodes/edges

Filter the instances - nodes and edges - in a project.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Filter based on the instance type, the name, the external-ids, and on properties. The filter supports sorting and pagination. The instances must have data in all the views referenced by the sources field. Properties for up to 10 views can be retrieved in one query.

includeTyping
boolean (IncludeTyping)
Default: false

Should we return property type information as part of the result?

Array of objects (SourceSelectorWithoutPropertiesV3) <= 10 items

Retrieve properties from the listed - by reference - views.

instanceType
string
Default: "node"
Enum: "node" "edge"

The type of instance you are querying for; an edge or a node. If the instance type isn't specified, we list nodes.

cursor
string
limit
integer [ 1 .. 1000 ]
Default: 1000

Limits the number of results to return.

Array of objects (PropertySortV3) <= 5 items
(BoolFilter (and (object) or or (object) or not (object))) or (LeafFilter (equals (object) or in (object) or range (object) or prefix (object) or exists (object) or containsAny (object) or containsAll (object) or matchAll (object) or nested (object) or overlaps (object) or hasData (object))) (FilterDefinition)

A filter Domain Specific Language (DSL) used to create advanced filter queries.

Responses

Request samples

Content type
application/json
{
  • "includeTyping": false,
  • "sources": [
    • {
      }
    ],
  • "instanceType": "node",
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
  • "limit": 1000,
  • "sort": [
    • {
      }
    ],
  • "filter": {
    • "and": [
      ]
    }
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "typing": {
    • "space-name1": {
      },
    • "space-name2": {
      }
    },
  • "nextCursor": "string"
}

Query nodes/edges

Querying

The Data Modelling API exposes an advanced query interface. The query interface supports parameterization, recursive edge traversal, chaining of result sets, and granular property selection.

A query is composed of a with section defining result set expressions that describe the input to the query, a set of optional parameter placeholders if the query is parameterized, and then the select section that defines which properties are to be returned back as part of the result.

Imagine you have a data set with airplanes and airports, represented as two sets of nodes with edges between them indicating in which airports the airplanes land. Here is an example of a query which fetches a specific airplane as well as the airports it lands in:

with:
    airplanes:
        nodes:
            filter:
                equals:
                    property: ["node", "externalId"]
                    value: {"parameter": "airplaneExternalId"}
        limit: 1
    lands_in_airports:
        edges:
            from: airplanes
            maxDistance: 1
            direction: outwards
            filter:
                equals:
                    property: ["edge", "type"]
                    value: ["aviation", "lands-in"]
    airports:
        nodes:
            from: lands_in_airports
parameters:
    airplaneExternalId: myFavouriteAirplane
select:
    airplanes: {}
    airports: {}

Result Set Expressions

Result set expressions appear directly below with in a query, and define a set of either nodes or edges. The set may be used to return results, as stepping stones to derive other sets from, or both. Result set expressions are named and can be chained as we'll see examples of later.

A result set expression may also define sort order and a limit. See sorting for more details.

While result set expressions may relate to each other via chaining, they don't have to. You can query for entirely unrelated things in the same query, but different sets are generally used to power graph traversals.

A set either queries nodes or it queries edges, possibly recursively.

All fields:

  • nodes: An object to specify a result set of matching nodes.
  • edges: An object to specify a result set of matching edges.
  • sort: A list of sort configurations
  • limit: How many nodes or edges to return in the result. Default: 100

Pagination

The max limit you can set for any table expression is 10,000. In order to support retrieving the entire result set, pagination cursors are emitted for each result set expression, allowing you to page through everything. Pagination cursors cannot be combined with custom sorts. If no pagination cursor is present for a given result set expression in the response, then there is guaranteed no more data that matches.

Node result set expressions

A nodes statement in your result set expression will make the set contain nodes.

A node result set can be chained off both node and edge result set expressions. When chaining off another node result set you will retrieve the nodes pointed to by a given direct relation property, this direct relation property is defined using the through field. When chaining off an edge result set, you will retrieve the end nodes defined by the edges in the set.

  • from: A different result set expression to chain from

  • through: What property to join the from "through". The through property must be a direct relation.

  • chainTo: Control which side of the edge to chain to. This option is only applicable if the view referenced in the from field consists of edges. chainTo can be one of:

    • source will chain to start if you're following edges outwards i.e direction=outwards. If you're following edges inwards i.e direction=inwards, it will chain to end.

    • destination (default) will chain to end if you're following edges outwards i.e direction=outwards. If you're following edges inwards i.e direction=inwards, it will chain to start.

  • filter: A filter to determine which nodes to match and thus be returned in the respective result set.

Edge result set expressions

An edges statement in a result set expression will make the set contain edges, and the statement defines the rules the graph traversal will follow.

A graph traversal can start from some initial set. This can be defined by from, which will name another result set expression.

The graph traversal follows edges in a particular direction, controlled by direction, which defaults to outwards.

    Alice -is_parent-> Bob
    Bob -fancies-> Mallory

Given the above graph, if you follow any edge from Bob outwards (which is default), you'll get the edges Bob -fancies-> Mallory. If you follow edges inwards, i.e. direction=inwards, you'll get Alice -is-parent-> Bob.

The traversal happens breadth first. See limitations for more details.

A traversal is defined by what edges to follow, what nodes to match, and what nodes to terminate traversal at.

This is controlled by filter, nodeFilter and terminationFilter.

filter is a filter on edges. You would typically filter on the property [edge, type], but any property on an edge can be filtered on.

nodeFilter is a node filter, which the node on the "other" side must match. With direction: outwards, that means the "end node" of the edge must match. With direction: inwards, the "start node" must match.

terminationFilter is similar to nodeFilter, except if it matches, traversal will end. A node must also match nodeFilter (if any) to steer the traversal to the node to terminate at in the first place.

maxDistance controls how many hops away from the initial set traversal will go. maxDistance defaults to unlimited (but the set must respect its limit, defined on the result set expression). If maxDistance is 1, execution might be faster, so if you know there will only be one level, it's worth configuring maxDistance: 1.

Full options:

  • from: Result set expression to chain from.
  • filter: Edges traversed must match this filter.
  • nodeFilter: Nodes on the "other" side of the edge must match this filter.
  • terminationFilter. Do not traverse beyond nodes matching this filter.
  • maxDistance: How many levels to traverse. Default unlimited.
  • direction: Whether to traverse edges pointing out of the initial set, or into the initial set.
  • limitEach: Limit the number of returned edges for each of the source nodes in the result set. The indicated uniform limit applies to the result set from the referenced from. limitEach only has meaning when you also specify maxDistance=1 and from.

Selects

Select configurations appear directly below select in a query. These specify which data to retrieve for the respective result set expression. It specifies a number of sources (views) and a property selector for each of these. The property selectors define which view properties will be emitted in the query result.

It's possible to have sets whose properties are not emitted. This can be useful if the sets are necessary for chaining, but not actually interesting to include in the final results. Sets that are neither chained nor selected will not be executed (but will cause very slight query processing overhead)

Results are grouped by their respective sets, and the results contain properties that match the property selectors for the set.

Filters

Filters define what a part of the query matches. Filters are tree structures where the operator comes first, and then the parameters for that operator.

A simple example is the in filter:

in:
    property: [node, name]
    values: [movie]

If the property node.name, which is text property, is equal to any of the values in the provided list, the node will match. Properties are typed. What query operators you can use on a property depends on its type.

An exhaustive list of filters and their descriptions can be found by examining the request body schema below.

Compound filters

Filters can be combined with and/or/not:

and:
    - not:
        in:
            property: [node, type]
            values: [movie]
    - range:
        property: [imdb, movie, released]
        gte: {parameter: start}

This would correspond to (NOT node.type in ('movie')) AND imdb.movie.released >= $start.

HasData filter

Although this filter is documentented in the request body schema, it merits a more detailed explanation. A hasData filters will match if data is present in a given set of containers or views.

There is an implicit AND between the containers and views referenced in the filter, so the filter will match if and only if the node/edge has data in all of the specified containers and views.

When a container is specified, the filter will match if the instance has all required properties populated for that particular container.

When a view is specified, the filter will match nodes with data in all of the containers which the view references through properties, respecting the filters of the view if defined (and the filters of views implemented by the view).

Example:

hasData:
    - type: container
      space: my_space
      externalId: my_container
    - type: view
      space: my_space
      externalId: my_view
      version: v1

If my_space.my_view.v1 maps properties in the containers my_space.c1 and my_space.c2. The filter will match if there is data in my_space.my_container AND (my_space.c1 AND my_space.c2) if there is no filter defined on my_space.my_view.v1, and my_space.my_container AND my_space.my_view.v1.filter if there is a filter defined on my_space.my_view.v1.

Parameters

Values in filters can be parameterised. Parameters are provided as part of the query object, and not in the filter itself.

This filter is parameterised:

range:
    property: [imdb, movie, released]
    gte: {parameter: start}

A query containing this filter will only run if the parameter start is provided. The parameter must be compatible with all the types and operators that refer to the parameter. In the above example, the "released" property is a date. Thus, the start parameter must be compatible with the date type, or the query will fail completely, even if the range filter is optional because it's OR-ed


TIP

Parameterise your filters!

It's a best practice to parameterise queries that take user input. This enables reusing query plans across queries, which will be noticable with read-heavy workloads.


Sorting and Limiting

Sorting and limiting can happen in multiple places in a query:

  • In the result set expression, i.e. in the with object that defines a node or edge set.
  • In the result selection, i.e. under select where defined sets can be emitted as results.

Sorting and limiting the set definitions under with will transitively affect dependent sets.

Changes to a set defined under with will naturally affect sets that depend on it, transitively. If you only change the sort order of a with expression, dependent sets will not (necessarily) change (based on how the dependent sets are defined), but if you put a limit on an expression, all dependent sets will inherit this and change as a consequence.

This is also true for sets that aren't actually emitted via select, i.e. sets that are only defined as stepping-stones for other sets.

Sorts and limits defined under select changes the result appearing order for that set only, and not for depending sets.

Example:

with:
    some_nodes:# omitted. No sort here
    some_edges:
        from: some_nodes
        # omitted. also no sorting
    target_nodes:
        from: some_edges
        # …
select:
    some_nodes:
        properties: ...
        sort:
            - {property: [node, created], direction: descending}
        limit: 100

The above query would still let some_edges and target_nodes pull from the full amount of nodes in some_nodes, even though what's returned as a result for some_nodes is capped at 100.

Order of sorting and limiting


NOTE

A limit in an edge traversal applies to when to start traversing, which happens before sorting.

Nodes and edges have subtly different sorting and limiting behaviour: Nodes sort and limit simultaneously, while recursive edge exploration do limited traversal, then sort.

The top-n set of nodes sorted by some property will be guaranteed to have the top-n of that property for the set.

For edges found through traversal, i.e. via edges, the limit applies to how many edges to discover. This may not be all the edges that could have been discovered in a full traversal. If you start traversing from some node and ask for 100 edges sorted by creation timestamp, the 100 edges discovered before traversal stops get sorted. The full graph is not traversed in order to find the 100 newest edges that exist in the graph defined by the traversal filters.

Therefore, to do sorting with a recursive graph traversal, you'll need to specify the sort configuration via postSort.

An edge traversal with maxDistance=1 can take a normal sort configuration, however.

Limitations

Graph traversal

Any query that involves a graph traversal will force nested loop-style execution. This will work well enough for traversals limited to a few hundred thousand unique paths.

The graph traversal is breadth first. All possible paths are traversed. This is important to keep in mind with traversals across loops. For example, a fully connected graph will not do well in a query that follows all possible paths, and is very likely to be terminated due to constraints on either time, memory, or temporary disk usage.

Timeout errors

Queries get cancelled with a 408 Request Timeout error if they take longer than the timeout. If hitting a timeout like this you will need to reduce load or contention, or optimise your query.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Query specification.

required
object [ 1 .. 50 ] properties
object <= 50 properties

Cursors returned from the previous query request. These cursors match the result set expressions you specified in the with clause for the query.

required
object [ 1 .. 50 ] properties
object

Values in filters can be parameterised. Parameters are provided as part of the query object, and referenced in the filter itself.

Responses

Request samples

Content type
application/json
{
  • "with": {
    • "result-expression-name1": {
      },
    • "result-expression-name2": {
      }
    },
  • "cursors": {
    • "pagination cursor reference1": "string",
    • "pagination cursor reference2": "string"
    },
  • "select": {
    • "result-expression-name1": {
      },
    • "result-expression-name2": {
      }
    },
  • "parameters": {
    • "parameter-identifier1": "string",
    • "parameter-identifier2": "string"
    }
}

Response samples

Content type
application/json
{
  • "items": {
    • "result-expression1": [
      ],
    • "result-expression2": [
      ]
    },
  • "nextCursor": {
    • "cursor-name1": "string",
    • "cursor-name2": "string"
    }
}

Retrieve nodes/edges by their external ids

Retrieve up to 1000 nodes or edges by their external ids.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

List of external-ids for nodes or edges to retrieve. Properties for up to 10 unique views (in total across the external ids requested) can be retrieved in one query.

Array of objects (SourceSelectorWithoutPropertiesV3) <= 10 items

Retrieve properties from the listed - by reference - views.

required
Array of objects [ 1 .. 1000 ] items
includeTyping
boolean (IncludeTyping)
Default: false

Should we return property type information as part of the result?

Responses

Request samples

Content type
application/json
{
  • "sources": [
    • {
      }
    ],
  • "items": [
    • {
      }
    ],
  • "includeTyping": false
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "typing": {
    • "space-name1": {
      },
    • "space-name2": {
      }
    }
}

Run inspection operations on instances

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Change filter specification

required
object
required
Array of objects [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "inspectionOperations": {
    • "involvedViewsAndContainers": {
      }
    },
  • "items": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ]
}

Search for nodes/edges

Search text fields in views for nodes or edge(s). The service will return up to 1000 results. This operation orders the results by relevance, across the specified spaces.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

The search specification.

required
object (ViewReference)

Reference to a view

query
string

Query string that will be parsed and used for search.

instanceType
string
Default: "node"
Enum: "node" "edge"

Limit the search query to searching nodes or edges. Unless you set the item type to apply the search to, the service will default to searching nodes within the view.

properties
Array of strings

Optional array of properties you want to search through. If you do not specify one or more properties, the service will search all text fields within the view.

(BoolFilter (and (object) or or (object) or not (object))) or (LeafFilter (equals (object) or in (object) or range (object) or prefix (object) or exists (object) or containsAny (object) or containsAll (object) or matchAll (object) or nested (object) or overlaps (object) or hasData (object))) (FilterDefinition)

A filter Domain Specific Language (DSL) used to create advanced filter queries.

limit
integer [ 1 .. 1000 ]
Default: 1000

Limits the number of results to return.

Responses

Request samples

Content type
application/json
{
  • "view": {
    • "type": "view",
    • "space": "string",
    • "externalId": "string",
    • "version": "string"
    },
  • "query": "string",
  • "instanceType": "node",
  • "properties": [
    • "string"
    ],
  • "filter": {
    • "and": [
      ]
    },
  • "limit": 1000
}

Response samples

Content type
application/json
{
  • "items": [
    • {
      }
    ],
  • "typing": {
    • "space-name1": {
      },
    • "space-name2": {
      }
    }
}

Sync nodes/edges

Subscribe to changes for nodes and edges in a project, matching a supplied filter. This endpoint will always return a NextCursor. The sync specification mirrors the query interface, but sorting is not currently supported.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json

Change filter specification

required
object [ 1 .. 50 ] properties
object <= 50 properties

Cursors returned from the previous sync request. These cursors match the result set expressions you specified in the with clause for the sync.

required
object [ 1 .. 50 ] properties
object

Parameters to return

Responses

Request samples

Content type
application/json
{
  • "with": {
    • "property1": {
      },
    • "property2": {
      }
    },
  • "cursors": {
    • "sync cursor reference1": "string",
    • "sync cursor reference2": "string"
    },
  • "select": {
    • "property1": {
      },
    • "property2": {
      }
    },
  • "parameters": {
    • "parameter-identifier1": "string",
    • "parameter-identifier2": "string"
    }
}

Response samples

Content type
application/json
{
  • "items": {
    • "result-expression1": [
      ],
    • "result-expression2": [
      ]
    },
  • "nextCursor": {
    • "cursor-name1": "string",
    • "cursor-name2": "string"
    }
}