Assets

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

Rate and concurrency limits

Both the rate of requests (denoted as request per second, or ‘rps’) and the number of concurrent (parallel) requests are governed by limits, for all CDF API endpoints. If a request exceeds one of the limits, it will be throttled with a 429: Too Many Requests response. More on limit types and how to avoid being throttled is described here.

Limits are defined at both the overall API service level, and on the API endpoints belonging to the service.
Some types of requests consume more resources (compute, storage IO) than others, and where a service handles multiple concurrent requests with varying resource consumption. For example, ‘CRUD’ type requests (Create, Retrieve, Request ByIDs, Update and Delete) are far less resource intensive than ‘Analytical’ type requests (List, Search and Filter) and in addition, the most resource intensive Analytical endpoint of all, Aggregates, receives its own request budget within the overall Analytical request budget.
The version 1.0 limits for the overall API service and its constituent endpoints are illustrated in the diagram below.
These limits are subject to change, pending review of changing consumption patterns and resource availability over time:

Translating RPS into data speed

A single request may retrieve up to 1000 items. In the context of Assets, 1 item = 1 asset record
Therefore, the maximum theoretical data speed at the top API service level is 200,000 items per second for all consumers, and 150,000 for a single identity or client in a project.

Use of Partitions / Parallel Retrieval

As a general guidance, Parallel Retrieval is a technique that should be used where due to query complexity, retrieval of data in a single request session turns out to be slow. By parallelizing such requests, data retrieval performance can be tuned to meet the client application needs. Parallel retrieval may also be used where retrieval of large sets of data is required, up to the capacity limits defined for a given API service. For example (using the Assets API request budget):

  • A single request may retrieve up to 1000 items
  • Up to 23 requests per second may be issued for an analytical query (per identity), such as when using /list or /filter API endpoints
  • This provides a theoretical maximum of 23,000 items read per second per identity
  • The query complexity may result in it taking longer than 1s to read or write 1000 items in a single request
  • Therefore, it is appropriate to specify the query to retrieve a lower number of items per request, and retrieve more items in parallel, up to the theoretical maximum performance of 23,000 items per second.

Important Note: Parallel retrieval should be only used in situations where, due to query complexity, a single request flow provides data retrieval speeds that are significantly less than the theoretical maximum.
Parallel retrieval does not act as a speed multiplier on optimally running queries. Regardless of the number of concurrent requests issued, the overall requests per second limit still applies.
So for example, a single request returning data at approximately 18,000 items per second will only benefit from adding a second parallel request, the capacity of which goes somewhat wasted as only an additional 5,000 items per second will return before the request rate budget limit is reached.

List assets

Required capabilities: assetsAcl:READ

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

Request throttling

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

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
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

Cursor for paging through results. In general, if a response contains a nextCursor property, it means that there may be more results, and you should pass that value as the cursor parameter in the next request.

Note that the cursor may or may not be encrypted, but either way, it is not intended to be decoded. Its internal structure is not a part of the public API, and may change without notice. You should treat it as an opaque string and not attempt to craft your own cursors.

Example: cursor=4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo
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)

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

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

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

Example: parentExternalIds=[externalId_1, externalId_2, externalId_3]
rootIds
string <jsonArray(int64)> (JsonArrayInt64)
Deprecated

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.

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

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.

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

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.

Example: assetSubtreeExternalIds=[externalId_1, externalId_2, externalId_3]
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.

Example: minCreatedTime=1730204346000
maxCreatedTime
integer <int64> (EpochTimestamp) >= 0

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

Example: maxCreatedTime=1730204346000
minLastUpdatedTime
integer <int64> (EpochTimestamp) >= 0

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

Example: minLastUpdatedTime=1730204346000
maxLastUpdatedTime
integer <int64> (EpochTimestamp) >= 0

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

Example: maxLastUpdatedTime=1730204346000
externalIdPrefix
string (CogniteExternalIdPrefix) <= 255 characters

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

Example: externalIdPrefix=my.known.prefix
partition
string

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.

The maximum number of allowed partitions (N) is 10.

Cognite rejects requests if you specify more than 10 partitions. When Cognite enforces this behavior, the requests result in a 400 Bad Request status.

Example: partition=1/3
Responses
200

Paged response with list of assets.

400

The response for a bad request.

429

The response for too many requests (concurrency or rate throttling).

get/assets
Request samples 
const assets = await client.assets.list({ filter: { name: '21PT1019' } });
Response samples
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Create assets

Required capabilities: assetsAcl:WRITE

Create multiple asset objects in the same project. It is possible to create a maximum of 1000 assets per request.

Request throttling

This endpoint is a subject of the new throttling schema (limited request rate and concurrency). Please check Assets resource description for more information.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
Request Body schema: application/json
required

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
201

Response with list of assets.

400

The response for a bad request.

429

The response for too many requests (concurrency or rate throttling).

post/assets
Request samples
application/json
{
  • "items": [
    ]
}
Response samples
application/json
{
  • "items": [
    ]
}

Retrieve an asset by its ID

Required capabilities: assetsAcl:READ

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

Request throttling

This endpoint is a subject of the new throttling schema (limited request rate and concurrency). Please check Assets resource description for more information.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
id
required
integer <int64> (CogniteInternalId) [ 1 .. 9007199254740991 ]

A server-generated ID for the object.

Responses
200

Response with a single asset.

400

The response for a bad request.

429

The response for too many requests (concurrency or rate throttling).

get/assets/{id}
Request samples 
const assets = await client.assets.retrieve([{id: 123}, {externalId: 'abc'}]);
Response samples
application/json
{
  • "createdTime": 1730204346000,
  • "lastUpdatedTime": 1730204346000,
  • "rootId": 1,
  • "aggregates": {
    },
  • "parentId": 1,
  • "parentExternalId": "my.known.id",
  • "externalId": "my.known.id",
  • "name": "string",
  • "description": "string",
  • "dataSetId": 1,
  • "metadata": {
    },
  • "source": "string",
  • "labels": [
    ],
  • "geoLocation": {
    },
  • "id": 1
}

Filter assets

Required capabilities: assetsAcl:READ

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

Advanced filtering

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

See the advancedFilter attribute in the example.

See more information about filtering DSL here.

Supported leaf filters

Leaf filter Supported fields Description
containsAll Array type fields Only includes results which contain all of the specified values.
{"containsAll": {"property": ["property"], "values": [1, 2, 3]}}
containsAny Array type fields Only includes results which contain at least one of the specified values.
{"containsAny": {"property": ["property"], "values": [1, 2, 3]}}
equals Non-array type fields Only includes results that are equal to the specified value.
{"equals": {"property": ["property"], "value": "example"}}
exists All fields Only includes results where the specified property exists (has value).
{"exists": {"property": ["property"]}}
in Non-array type fields Only includes results that are equal to one of the specified values.
{"in": {"property": ["property"], "values": [1, 2, 3]}}
prefix String type fields Only includes results which start with the specified value.
{"prefix": {"property": ["property"], "value": "example"}}
range Non-array type fields Only includes results that fall within the specified range.
{"range": {"property": ["property"], "gt": 1, "lte": 5}}
Supported operators: gt, lt, gte, lte
search ["name"], ["description"] Introduced to provide functional parity with /assets/search endpoint.
{"search": {"property": ["property"], "value": "example"}}

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

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

advancedFilter attribute limits

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

Sorting

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

See the sort attribute in the example.

Null values

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

Sorting by score

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

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

Request throttling

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

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
Request Body schema: application/json
object (Filter)

Filter on assets with strict matching.

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

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

See more information about filtering DSL here.

Supported properties:

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

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

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

Limits the number of results to return.

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

Sort by array of selected properties.

cursor
string
aggregatedProperties
Array of strings (AggregatedProperty)

Set of aggregated properties to include

Items Enum: "childCount" "path" "depth"
partition
string (PartitionLimited10)

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.

The maximum number of allowed partitions (N) is 10.

Cognite rejects requests if you specify more than 10 partitions. When Cognite enforces this behavior, the requests result in a 400 Bad Request status.

Responses
200

Paged response with list of assets.

400

The response for a bad request.

429

The response for too many requests (concurrency or rate throttling).

post/assets/list
Request samples
application/json
{
  • "filter": {
    },
  • "advancedFilter": {
    },
  • "limit": 100,
  • "sort": [
    ],
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
  • "aggregatedProperties": [
    ],
  • "partition": "1/3"
}
Response samples
application/json
{
  • "items": [
    ],
  • "nextCursor": "string"
}

Aggregate assets

Required capabilities: assetsAcl:READ

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

Aggregate filtering

Filter (filter & advancedFilter) data for aggregates

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

aggregateFilter to filter aggregate results

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

Request throttling

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

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
Request Body schema: application/json
One of:

Request aggregate to count number of Assets matching the filters. Default aggregate for the endpoint.

aggregate
string

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

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

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

See more information about filtering DSL here.

Supported properties:

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

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

object (Filter)

Filter on assets with strict matching.

Responses
200

Response with a list of aggregation results.

400

The response for a bad request.

429

The response for too many requests (concurrency or rate throttling).

post/assets/aggregate
Request samples
application/json
{
  • "aggregate": "count",
  • "advancedFilter": {
    },
  • "filter": {
    }
}
Response samples
application/json
{
  • "items": [
    ]
}

Retrieve assets

Required capabilities: assetsAcl:READ

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

Request throttling

This endpoint is a subject of the new throttling schema (limited request rate and concurrency). Please check Assets resource description for more information.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
Request Body schema: application/json
required

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)

Set of aggregated properties to include

Items Enum: "childCount" "path" "depth"
Responses
200

Response with list of assets.

400

The response for a bad request.

429

The response for too many requests (concurrency or rate throttling).

post/assets/byids
Request samples
application/json
{
  • "items": [
    ],
  • "ignoreUnknownIds": false,
  • "aggregatedProperties": [
    ]
}
Response samples
application/json
{
  • "items": [
    ]
}

Update assets

Required capabilities: assetsAcl:WRITE

Update the attributes of assets.

Request throttling

This endpoint is a subject of the new throttling schema (limited request rate and concurrency). Please check Assets resource description for more information.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
Request Body schema: application/json
required

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
200

Response with list of assets.

400

The response for a bad request.

429

The response for too many requests (concurrency or rate throttling).

post/assets/update
Request samples
application/json
{
  • "items": [
    ]
}
Response samples
application/json
{
  • "items": [
    ]
}

Search assets

Required capabilities: assetsAcl:READ

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

Request throttling

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

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
Request Body schema: application/json
required

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
200

Response with list of assets.

400

The response for a bad request.

429

The response for too many requests (concurrency or rate throttling).

post/assets/search
Request samples
application/json
{
  • "filter": {
    },
  • "search": {
    }
}
Response samples
application/json
{
  • "items": [
    ]
}

Delete assets

Required capabilities: assetsAcl:WRITE

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.

Request throttling

This endpoint is a subject of the new throttling schema (limited request rate and concurrency). Please check Assets resource description for more information.

Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
Request Body schema: application/json
required
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
200

Empty response.

400

The response for a bad request.

429

The response for too many requests (concurrency or rate throttling).

post/assets/delete
Request samples
application/json
{
  • "items": [
    ],
  • "recursive": false,
  • "ignoreUnknownIds": false
}
Response samples
application/json
{ }
➔ Next to Time series