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

You can download our postman collection here. Open Postman, click Import -> Import From Link, insert the link and import.

You can read more about how to use Postman here

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.

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.

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": {
    • "max": 0,
    • "min": 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.

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.

In beta. Available only when the cdf-version header with the beta suffix value is provided.

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.

Aggregate requests throttling

The aggregate requests are a subject of the new throttling schema (limited requests rate and concurrency). The schema is in the design stage now and will be released when the new aggregate goes into LA/GA.

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.

In beta. Available only when the cdf-version header with the beta suffix value is provided.

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": [
      ],
    • "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.

In beta. Available only when the cdf-version header with the beta suffix value is provided.

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

advancedFilter attribute requests throttling

The requests with the advancedFilter attribute is a subject of the new throttling schema (limited requests rate and concurrency). The schema is in the design stage now and will be released when the Advanced filtering goes LA/GA.

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.

In beta. Available only when the cdf-version header with the beta suffix value is provided.

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_"]
  }
]
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.

In beta. Available only when the cdf-version header with the beta suffix value is provided.

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.

In beta. Available only when the cdf-version header with the beta suffix value is provided.

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": [
      ],
    • "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.

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.

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": [
    • {
      }
    ]
}

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 fields advancedFilter, aggregateFilter, and aggregate, are in beta. They are available only when the cdf-version header with the value beta is provided. Without that header, only the default behavior described below (when aggregate is not specified) is available.

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.

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.

In beta. Available only when the cdf-version header with the value beta is provided.

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.

In beta. Available only when the cdf-version header with the value beta is provided.

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.

In beta. Available only when the cdf-version header with the value beta is provided.

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.

The fields advancedFilter and sort are in beta. They are available only when the cdf-version header with the value beta is provided.

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.

In beta. Available only when the cdf-version header with the value beta is provided.

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.

In beta. Available only when the cdf-version header with the value beta is provided.

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": [
    • {
      }
    ]
}

Data point subscriptions

A data point subscription is a way to listen to changes to time series data points, in ingestion order.

A single subscription can listen to many time series, and a time series can be part of many subscriptions.

You listen to subscriptions by calling the “list subscription data“ endpoint. It will return a list of data point upserts and deleted ranges, together with a cursor to retrieve the next batch of updates. It will store updates from when the subscription was created, but updates older than 7 days may be discarded.

Subscriptions can be defined explicitly through a list of time series external ids, or implicitly through a filter. The filter is a subset of the advanced filter query in the regular “time series search“ endpoint.

Partitions: Subscriptions can be further divided into a number of partitions, for the purpose of fetching subscription data in parallel. Each partition will return data in ingestion order, but the order between partitions is not guaranteed.

Limitations (may be subject to change):

  • Each subscription can have at most 10000 time series
  • A time series can be part of at most 10 subscriptions
  • A project can have at most 100 subscriptions, of which 50 filter subscriptions
  • Time series with security categories can not be shown in filter subscriptions
  • Time series without externalId cannot be added to non-filter subscriptions
  • The number of partitions cannot be changed after creation

Beta: Subscriptions are available only when the cdf-version header with the value beta is provided.

Access control: You need to have experimental access to timeseries-subscriptions as long as subscriptions are in beta. You also need READ access to subscriptions ACL to read/list subscriptions or list data, and you need WRITE access to create/update/delete subscriptions. Furthermore, you need READ access to the time series you want to get updates from. For filter subscriptions, you either need READ access to all time series, or the filter must be restricted according to your access rights (e.g. by filtering on specific data set IDs).

Example capabilities:

[
    {"timeSeriesAcl":{"actions":["READ"], "scope":{"all":{}}}},
    {"timeSeriesSubscriptionsAcl":{"actions":["WRITE", "READ"], "scope":{"all":{}}}},
    {"experimentAcl":{"actions":["USE"], "scope":{"experimentscope":{"experiments":["timeseries-subscription"]}}}}
]

Create subscriptions

Create one or more subscriptions that can be used to listen for changes in data points for a set of time series. All subscription endpoints require experimental acl access, USE the timeseries-subscription experiment. Contact cognite support for more information.

In beta. Available only when the cdf-version header with the value beta is provided.

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

The subscriptions to create.

required
Array of objects = 1 items

Retrieves a list of time series that match the given criteria.

Advanced filtering

The filter 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

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

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).
  • The maximum length of the value of a leaf filter that is applied to a string property is 256.

Responses

Request samples

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

Response samples

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

Delete subscriptions

Delete subscription(s). This operation cannot be undone

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

Specify a list of the subscriptions to delete.

required
Array of objects (QueryWithExternalId) [ 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
{ }

List subscription data

Fetch the next batch of data from a given subscription and partition(s). Data can be ingested datapoints and time ranges where data is deleted. This endpoint will also return changes to the subscription itself, that is, if time series are added or removed from the subscription.

Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
externalId
string (CogniteExternalId) <= 255 characters

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

required
Array of objects (SubscriptionsDataPartitionRequestDTO)

Pairs of (partition, cursor) to fetch from.

limit
integer [ 1 .. 100000 ]
Default: 100

Approximate number of results to return across all partitions. We will batch together groups of updates, where each group come from the same ingestion request. Thus, if a single group is large, it may exceed limit, otherwise we will return up to limit results. To check whether you have reached the end, do not rely on the count. Instead, check the hasNext field.

Responses

Request samples

Content type
application/json
{
  • "externalId": "my.known.id",
  • "partitions": [
    • {
      }
    ],
  • "limit": 100
}

Response samples

Content type
application/json
{
  • "updates": [
    • {
      }
    ],
  • "subscriptionChanges": {
    • "added": [
      ],
    • "removed": [
      ]
    },
  • "partitions": [
    • {
      }
    ],
  • "hasNext": true
}

List subscriptions.

List all subscriptions for the tenant. Use nextCursor to paginate through the results.

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

Limit on the number of results to return.

cursor
string
Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo

Cursor for paging through results.

Responses

Response samples

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

Retrieve subscriptions

Retrieve one or more subscriptions by external ID.

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

Specify a list of the subscriptions to retrieve.

required
Array of objects (QueryWithExternalId) = 1 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": [
    • {
      }
    ]
}

Update subscriptions

Updates one or more subscriptions. 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

The subscriptions to update

required
Array of objects (Select by externalId) = 1 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.

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.

In beta. Available only when the cdf-version header with the beta suffix value is provided.

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.

Aggregate requests throttling

The aggregate requests are a subject of the new throttling schema (limited requests rate and concurrency). The schema is in the design stage now and will be released when the new aggregate goes into LA/GA.

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

Filter on events filter with exact match

aggregate
string
Value: "count"

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

In beta. Available only when the cdf-version header with the beta suffix value is provided.

(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.

In beta. Available only when the cdf-version header with the beta suffix value is provided.

Responses

Request samples

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

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.

In beta. Available only when the cdf-version header with the beta suffix value is provided.

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

advancedFilter attribute requests throttling

The requests with the advancedFilter attribute is a subject of the new throttling schema (limited requests rate and concurrency). The schema is in the design stage now and will be released when the Advanced filtering goes into LA/GA.

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_"]
  }
]
Authorizations:
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Request Body schema: application/json
object (EventFilter)

Filter on events filter with exact match

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 modern (objects) or Array of deprecated (strings)
(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.

In beta. Available only when the cdf-version header with the beta suffix value is provided.

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": [
      ],
    • "dataSetIds": [
      ],
    • "source": "string",
    • "type": "string",
    • "subtype": "string",
    • "createdTime": {
      },
    • "lastUpdatedTime": {
      },
    • "externalIdPrefix": "my.known.prefix"
    },
  • "limit": 100,
  • "sort": [
    • {
      },
    • {
      }
    ],
  • "advancedFilter": {
    • "or": [
      ]
    },
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
  • "partition": "1/10"
}

Response samples

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

List events

List events optionally filtered on query 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.

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.

<