openapi: 3.1.0
info:
title: Cognite 3D Asset Mapping Assets API
description: "# Introduction\nThis is the reference documentation for the Cognite API with\nan overview of all the available methods.\n\n# Postman\nSelect the **Download** button to download our OpenAPI specification to get started.\n\nTo import your data into Postman, select **Import**, and the Import modal opens.\nYou can import items by dragging or dropping files or folders. You can choose how to import your API and manage the import settings in **View Import Settings**.\n\nIn the Import Settings, set the **Folder organization** to **Tags**, select\n**Enable optional parameters** to turn off the settings, and select **Always inherit authentication** to turn on the settings. Select **Import**.\n\nSet the Authorization to **Oauth2.0**. By default, the settings are for Open Industrial Data. Navigate to [Cognite Hub](https://hub.cognite.com/open-industrial-data-211) to understand how to get the credentials for use in Postman.\n\nFor more information, see [Getting Started with Postman](https://developer.cognite.com/dev/guides/postman/).\n\n# Pagination\nMost resource types can be paginated, indicated by the field `nextCursor` in the response.\nBy passing the value of `nextCursor` as the cursor you will get the next page of `limit` results.\nNote that all parameters except `cursor` has to stay the same.\n\n# Parallel retrieval\nAs general guidance, Parallel Retrieval is a technique that should be used when due to query complexity, retrieval of data in a single request is significantly slower than it would otherwise be for a simple request. Parallel retrieval does not act as a speed multiplier on optimally running queries. By parallelizing such requests, data retrieval performance can be tuned to meet the client application needs. \n\nCDF supports parallel retrieval through the `partition` parameter, which has the format `m/n` where `n` is the amount of partitions you would like to split the entire data set into.\nIf 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:\n - Make a request to `/events` with `partition=m/10`.\n - Paginate through the response by following the cursor as explained above. Note that the `partition` parameter needs to be passed to all subqueries.\n\nProcessing 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.\n\nTo prevent unexpected problems and to maximize read throughput, you should at most use 10 partitions. \nSome CDF resources will automatically enforce a maximum of 10 partitions.\nFor more specific and detailed information, please read the ```partition``` attribute documentation for the CDF resource you're using. \n\n# Requests throttling\nCognite Data Fusion (CDF) returns the HTTP `429` (too many requests) response status code when project capacity exceeds the limit.\n\nThe throttling can happen:\n - If a user or a project sends too many (more than allocated) concurrent requests.\n - If a user or a project sends a too high (more than allocated) rate of requests in a given amount of time.\n\nCognite recommends using a retry strategy based on truncated exponential backoff to handle sessions with HTTP response codes 429.\n\nCognite recommends using a reasonable number (up to 10) of `Parallel retrieval` partitions.\n\nFollowing these strategies lets you slow down the request frequency to maximize productivity without having to re-submit/retry failing requests.\n\nSee more [here](https://docs.cognite.com/dev/concepts/resource_throttling).\n\n# API versions\n## Version headers\nThis API uses calendar versioning, and version names follow the `YYYYMMDD` format.\nYou can find the versions currently available by using the version selector at the top of this page.\n\nTo use a specific API version, you can pass the `cdf-version: $version` header along with your requests to the API.\n\n## Beta versions\nThe beta versions provide a preview of what the stable version will look like in the future.\nBeta versions contain functionality that is reasonably mature, and highly likely to become a part of the stable API.\n\nBeta versions are indicated by a `-beta` suffix after the version name. For example, the beta version header for the\n2023-01-01 version is then `cdf-version: 20230101-beta`.\n\n## Alpha versions\nAlpha versions contain functionality that is new and experimental, and not guaranteed to ever become a part of the stable API.\nThis functionality presents no guarantee of service, so its use is subject to caution.\n\nAlpha versions are indicated by an `-alpha` suffix after the version name. For example, the alpha version header for\nthe 2023-01-01 version is then `cdf-version: 20230101-alpha`."
version: v1
contact:
name: Cognite Support
url: https://support.cognite.com
email: support@cognite.com
servers:
- url: https://{cluster}.cognitedata.com/api/v1/projects/{project}
description: The URL for the CDF cluster to connect to
variables:
cluster:
enum:
- api
- az-tyo-gp-001
- az-eastus-1
- az-power-no-northeurope
- westeurope-1
- asia-northeast1-1
- gc-dsm-gp-001
default: api
description: The CDF cluster to connect to
project:
default: publicdata
description: The CDF project name.
security:
- oidc-token:
- https://{cluster}.cognitedata.com/.default
- oauth2-client-credentials:
- https://{cluster}.cognitedata.com/.default
- oauth2-open-industrial-data:
- https://api.cognitedata.com/.default
- oauth2-auth-code:
- https://{cluster}.cognitedata.com/.default
tags:
- name: Assets
description: "The assets resource type stores digital representations of objects or\ngroups of objects from the physical world. Assets are organized in hierarchies.\nFor example, a water pump asset can be a part of a subsystem asset on an\noil platform asset.\n\n## Rate and concurrency limits\n\nBoth the rate of requests (denoted as request per second, or â\x80\x98**rps**â\x80\x99) and the number of concurrent (parallel) requests are governed by limits,\nfor all CDF API endpoints. If a request exceeds one of the limits,\nit will be throttled with a `429: Too Many Requests` response. More on limit types\nand how to avoid being throttled is described\n[here](https://docs.cognite.com/dev/concepts/resource_throttling).\n\nLimits are defined at both the overall API service level, and on the API endpoints belonging to the service.\\\nSome types of requests consume more resources (compute, storage IO) than others, and where a service handles\nmultiple concurrent requests with varying resource consumption.\nFor example, â\x80\x98CRUDâ\x80\x99 type requests (**C**reate, **R**etrieve, **R**equest ByIDs, **U**pdate and **D**elete) are far less resource\nintensive than â\x80\x98Analyticalâ\x80\x99 type requests (List, Search and Filter) and in addition, the most resource\nintensive Analytical endpoint of all, Aggregates, receives its own request budget within the overall Analytical request budget.\\\nThe version 1.0 limits for the overall API service and its constituent endpoints are illustrated in the diagram below.\\\nThese limits are subject to change, pending review of changing consumption patterns and resource availability over time:\n\n<img src=\"https://apps-cdn.cogniteapp.com/@cognite/docs-portal-images/1.0.0/images/api-docs/AssetsLimitsFeb2023.png\" alt=\" \" width=\"80%\"/>\n\n### Translating RPS into data speed\nA single request may retrieve up to 1000 items. In the context of Assets, 1 item = 1 asset record\\\nTherefore, the maximum theoretical data speed at the top API service level is 200,000 items per second for all consumers,\nand 150,000 for a single identity or client in a project.\n\n### Use of Partitions / Parallel Retrieval\nAs a general guidance, Parallel Retrieval is a technique that should be used where due to query complexity, retrieval of data in a\nsingle request session turns out to be slow. By parallelizing such requests, data retrieval performance can be tuned to meet the\nclient application needs. Parallel retrieval may also be used where retrieval of large sets of data is required, up to the\ncapacity limits defined for a given API service. For example (using the Assets API request budget):\n\n* A single request may retrieve up to 1000 items\n* Up to 23 requests per second may be issued for an analytical query (per identity), such as when using /list or /filter API endpoints\n* This provides a theoretical maximum of 23,000 items read per second per identity\n* The query complexity may result in it taking longer than 1s to read or write 1000 items in a single request\n* 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.\n\n**Important Note:**\nParallel retrieval should be only used in situations where, due to query complexity,\na single request flow provides data retrieval speeds that are significantly less than the theoretical maximum.\\\nParallel retrieval does not act as a speed multiplier on optimally running queries. Regardless of the number\nof concurrent requests issued, the overall requests per second limit still applies.\\\nSo for example, a single request returning data at approximately 18,000 items per second will only\nbenefit from adding a second parallel request, the capacity of which goes somewhat wasted\nas only an additional 5,000 items per second will return before the request rate budget limit is reached."
paths:
/assets:
get:
tags:
- Assets
summary: List assets
description: '
> **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.'
operationId: getAssets
parameters:
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/IncludeMetadata'
- in: query
name: name
schema:
$ref: '#/components/schemas/AssetName'
- in: query
name: parentIds
description: List only assets that have one of the parentIds as a parent. The parentId for root assets is null.
example: '[363848954441724, 793045462540095, 1261042166839739]'
schema:
$ref: '#/components/schemas/JsonArrayInt64'
- in: query
name: parentExternalIds
description: List only assets that have one of the parentExternalIds as a parent. The parentId for root assets is null.
example: '[externalId_1, externalId_2, externalId_3]'
schema:
$ref: '#/components/schemas/JsonArrayString'
- in: query
name: rootIds
description: 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: '[363848954441724, 793045462540095, 1261042166839739]'
deprecated: true
schema:
$ref: '#/components/schemas/JsonArrayInt64'
- in: query
name: assetSubtreeIds
description: 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: '[363848954441724, 793045462540095, 1261042166839739]'
schema:
$ref: '#/components/schemas/JsonArrayInt64'
- in: query
name: assetSubtreeExternalIds
description: 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: '[externalId_1, externalId_2, externalId_3]'
schema:
$ref: '#/components/schemas/JsonArrayString'
- in: query
name: source
schema:
maxLength: 128
type: string
description: The source of the asset, for example which database it's from.
- in: query
name: root
schema:
type: boolean
default: false
description: Whether the filtered assets are root assets, or not. Set to True to only list root assets.
- in: query
name: minCreatedTime
schema:
$ref: '#/components/schemas/EpochTimestamp'
- in: query
name: maxCreatedTime
schema:
$ref: '#/components/schemas/EpochTimestamp'
- in: query
name: minLastUpdatedTime
schema:
$ref: '#/components/schemas/EpochTimestamp'
- in: query
name: maxLastUpdatedTime
schema:
$ref: '#/components/schemas/EpochTimestamp'
- in: query
name: externalIdPrefix
schema:
$ref: '#/components/schemas/CogniteExternalIdPrefix'
- $ref: '#/components/parameters/partitionLimited10'
responses:
'200':
$ref: '#/components/responses/AssetDataWithCursorResponse'
'400':
$ref: '#/components/responses/400ErrorResponse'
'429':
$ref: '#/components/responses/429ErrorResponse'
x-capability:
- assetsAcl:READ
x-code-samples:
- lang: JavaScript
label: JavaScript SDK
source: 'const assets = await client.assets.list({ filter: { name: ''21PT1019'' } });'
- lang: Python
label: Python SDK
source: "from cognite.client.data_classes import filters\nin_timezone = filters.Prefix([\"metadata\", \"timezone\"], \"Europe\")\nres = client.assets.filter(filter=in_timezone, sort=(\"external_id\", \"asc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.assets import AssetProperty, SortableAssetProperty\nin_timezone = filters.Prefix(AssetProperty.metadata_key(\"timezone\"), \"Europe\")\nres = client.assets.filter(\n filter=in_timezone,\n sort=(SortableAssetProperty.external_id, \"asc\"))\nasset_list = client.assets.list(limit=5)\n\nfor asset in client.assets:\n asset # do something with the asset\n\nfor asset_list in client.assets(chunk_size=2500):\n asset_list # do something with the assets\n\nfrom cognite.client.data_classes import LabelFilter\nmy_label_filter = LabelFilter(contains_all=[\"PUMP\", \"VERIFIED\"])\nasset_list = client.assets.list(labels=my_label_filter)\n\nfrom cognite.client.data_classes import filters\nin_timezone = filters.Prefix([\"metadata\", \"timezone\"], \"Europe\")\nres = client.assets.list(advanced_filter=in_timezone, sort=(\"external_id\", \"asc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.assets import AssetProperty, SortableAssetProperty\nin_timezone = filters.Prefix(AssetProperty.metadata_key(\"timezone\"), \"Europe\")\nres = client.assets.list(\n advanced_filter=in_timezone,\n sort=(SortableAssetProperty.external_id, \"asc\"))\n\nfrom cognite.client.data_classes import filters\nnot_instrument_lvl5 = filters.And(\n filters.ContainsAny(\"labels\", [\"Level5\"]),\n filters.Not(filters.ContainsAny(\"labels\", [\"Instrument\"]))\n)\nres = client.assets.list(asset_subtree_ids=[123456], advanced_filter=not_instrument_lvl5)\n"
post:
tags:
- Assets
summary: Create assets
description: '
> **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.'
operationId: createAssets
requestBody:
description: List of the assets to create. You can create a maximum of 1000 assets per request.
content:
application/json:
schema:
$ref: '#/components/schemas/DataExternalAsset'
required: true
responses:
'201':
$ref: '#/components/responses/AssetDataResponse'
'400':
$ref: '#/components/responses/400ErrorResponse'
'429':
$ref: '#/components/responses/429ErrorResponse'
x-capability:
- assetsAcl:WRITE
x-code-samples:
- lang: JavaScript
label: JavaScript SDK
source: "const assets = [\n { name: 'First asset' },\n { name: 'Second asset', description: 'Another asset', externalId: 'anotherAsset' },\n { name: 'Child asset', parentExternalId: 'anotherAsset'},\n];\nconst createdAssets = await client.assets.create(assets);"
- lang: Python
label: Python SDK
source: 'from cognite.client.data_classes import AssetWrite
assets = [AssetWrite(name="asset1"), AssetWrite(name="asset2")]
res = client.assets.create(assets)
from cognite.client.data_classes import AssetWrite, Label
asset = AssetWrite(name="my_pump", labels=[Label(external_id="PUMP")])
res = client.assets.create(asset)
'
- lang: Java
label: Java SDK
source: "List<Asset> upsertAssetsList = List.of(Asset.newBuilder()\n .setExternalId(\"10\")\n .setName(\"generated_asset_\")\n .setDescription(\"generated_asset_description_\")\n .setSource(\"sdk-data-generator\")\n .putMetadata(\"type\", \"sdk-data-generator\")\n .build()); \nList<Asset> upsertedAssets = client.assets().upsert(upsertAssetsList); \n\n"
/assets/{id}:
get:
tags:
- Assets
summary: Retrieve an asset by its ID
description: '
> **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.'
operationId: getAsset
parameters:
- $ref: '#/components/parameters/CogniteInternalId'
responses:
'200':
$ref: '#/components/responses/AssetResponse'
'400':
$ref: '#/components/responses/400ErrorResponse'
'429':
$ref: '#/components/responses/429ErrorResponse'
x-capability:
- assetsAcl:READ
x-code-samples:
- lang: JavaScript
label: JavaScript SDK
source: 'const assets = await client.assets.retrieve([{id: 123}, {externalId: ''abc''}]);'
- lang: Python
label: Python SDK
source: 'res = client.assets.retrieve(id=1)
res = client.assets.retrieve(external_id="1")
'
/assets/list:
post:
tags:
- Assets
summary: Filter assets
description: "\n\n> **Required capabilities:** `assetsAcl:READ`\n\nRetrieve a list of assets in the same project. This operation supports pagination by cursor.\nApply Filtering and Advanced filtering criteria to select a subset of assets.\n\n### Advanced filtering\nAdvanced filter lets you create complex filtering expressions that combine simple operations,\nsuch as `equals`, `prefix`, `exists`, etc., using boolean operators `and`, `or`, and `not`.\nIt applies to basic fields as well as metadata.\n\nSee the `advancedFilter` attribute in the example.\n\nSee more information about filtering DSL [here](https://docs.cognite.com/dev/concepts/resource_filtering_dsl/ \"filtering DSL\").\n\n#### Supported leaf filters\n\n| Leaf filter | Supported fields | Description |\n|----------------|------------------------------------|--------------|\n| `containsAll` | Array type fields | Only includes results which contain all of the specified values. <br /> `{\"containsAll\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `containsAny` | Array type fields | Only includes results which contain at least one of the specified values. <br /> `{\"containsAny\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `equals` | Non-array type fields | Only includes results that are equal to the specified value. <br /> `{\"equals\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n| `exists` | All fields | Only includes results where the specified property exists (has value). <br /> `{\"exists\": {\"property\": [\"property\"]}}` |\n| `in` | Non-array type fields | Only includes results that are equal to one of the specified values. <br /> `{\"in\": {\"property\": [\"property\"], \"values\": [1, 2, 3]}}` |\n| `prefix` | String type fields | Only includes results which start with the specified value. <br /> `{\"prefix\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n| `range` | Non-array type fields | Only includes results that fall within the specified range. <br /> `{\"range\": {\"property\": [\"property\"], \"gt\": 1, \"lte\": 5}}` <br /> Supported operators: `gt`, `lt`, `gte`, `lte` |\n| `search` | `[\"name\"]`, `[\"description\"]` | Introduced to provide functional parity with /assets/search endpoint. <br /> `{\"search\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n\n##### Search\nThe `search` leaf filter provides functional parity with the `/assets/search` endpoint.\nIt's available only for the `[\"description\"]` and `[\"name\"]` properties. When specifying only this filter with no explicit ordering,\nbehavior is the same as of the `/assets/search/` endpoint without specifying filters.\nExplicit sorting overrides the default ordering by relevance.\nIt's possible to use the `search` leaf filter as any other leaf filter for creating complex queries.\n\nSee the `search` filter in the `advancedFilter` attribute in the example.\n\n#### advancedFilter attribute limits\n- filter query max depth: 10\n- filter query max number of clauses: 100\n- `and` and `or` clauses must have at least one element\n- `property` array of each leaf filter has the following limitations:\n - number of elements in the array is in the range [1, 2]\n - elements must not be blank\n - each element max length is 128 symbols\n - property array must match one of the existing properties (static or dynamic metadata).\n- `containsAll`, `containsAny`, and `in` filter `values` array size must be in the range [1, 100]\n- `containsAll`, `containsAny`, and `in` filter `values` array must contain elements of a primitive type (number, string)\n- `range` filter must have at least one of `gt`, `gte`, `lt`, `lte` attributes.\n But `gt` is mutually exclusive to `gte`, while `lt` is mutually exclusive to `lte`.\n At least one of the bounds must be specified.\n- `gt`, `gte`, `lt`, `lte` in the `range` filter must be a primitive value\n- `search` filter `value` must not be blank and the length must be in the range [1, 128]\n- filter query may have maximum 2 search leaf filters\n- maximum leaf filter string value length is different depending on the property the filter is using:\n - `externalId` - 255\n - `name` - 128 for the `search` filter and 255 for other filters\n - `description` - 128 for the `search` filter and 255 for other filters\n - `labels` item - 255\n - `source` - 128\n - any `metadata` key - 128\n\n### Sorting\nBy default, assets are sorted by `id` in the ascending order.\nUse the `search` leaf filter to sort the results by relevance.\nSorting by other fields can be explicitly requested. The `order` field is optional\nand defaults to `desc` for `_score_` and `asc` for all other fields.\nThe `nulls` field is optional and defaults to `auto`. `auto` is translated to\n`last` for the `asc` order and to `first` for the `desc` order by the service.\nPartitions are done independently of sorting; there's no guarantee of the sort order between elements from different partitions.\n\nSee the `sort` attribute in the example.\n\n#### Null values\nIn case the `nulls` attribute has the `auto` value or the attribute isn't specified,\nnull (missing) values are considered to be bigger than any other values.\nThey are placed last when sorting in the `asc` order and first when sorting in `desc`.\nOtherwise, missing values are placed according to the `nulls` attribute (last or first), and their placement doesn't depend on the `order` value.\nValues, such as empty strings, aren't considered as nulls.\n\n#### Sorting by score\nUse a special sort property `_score_` when sorting by relevance.\nThe more filters a particular asset matches, the higher its score is. This can be useful,\nfor example, when building UIs. Let's assume we want exact matches to be be displayed above matches by\nprefix as in the request below. An asset named `pump` will match both `equals` and `prefix`\nfilters and, therefore, have higher score than assets with names like `pump valve` that match only `prefix` filter.\n\n```\n\"advancedFilter\" : {\n \"or\" : [\n {\n \"equals\": {\n \"property\": [\"name\"],\n \"value\": \"pump\"\n }\n },\n {\n \"prefix\": {\n \"property\": [\"name\"],\n \"value\": \"pump\"\n }\n }\n ]\n},\n\"sort\": [\n {\n \"property\" : [\"_score_\"]\n }\n]\n```\n\n### Request throttling\nThis endpoint is meant for data analytics/exploration usage and is not suitable for high load data retrieval usage.\nIt is a subject of the new throttling schema (limited request rate and concurrency).\nPlease check [Assets resource description](../../) for more information."
operationId: listAssets
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AssetListScope'
responses:
'200':
$ref: '#/components/responses/AssetDataWithCursorResponse'
'400':
$ref: '#/components/responses/400ErrorResponse'
'429':
$ref: '#/components/responses/429ErrorResponse'
x-capability:
- assetsAcl:READ
x-code-samples:
- lang: JavaScript
label: JavaScript SDK
source: 'const assets = await client.assets.list({ filter: { name: ''21PT1019'' } });'
- lang: Python
label: Python SDK
source: "from cognite.client.data_classes import filters\nin_timezone = filters.Prefix([\"metadata\", \"timezone\"], \"Europe\")\nres = client.assets.filter(filter=in_timezone, sort=(\"external_id\", \"asc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.assets import AssetProperty, SortableAssetProperty\nin_timezone = filters.Prefix(AssetProperty.metadata_key(\"timezone\"), \"Europe\")\nres = client.assets.filter(\n filter=in_timezone,\n sort=(SortableAssetProperty.external_id, \"asc\"))\nasset_list = client.assets.list(limit=5)\n\nfor asset in client.assets:\n asset # do something with the asset\n\nfor asset_list in client.assets(chunk_size=2500):\n asset_list # do something with the assets\n\nfrom cognite.client.data_classes import LabelFilter\nmy_label_filter = LabelFilter(contains_all=[\"PUMP\", \"VERIFIED\"])\nasset_list = client.assets.list(labels=my_label_filter)\n\nfrom cognite.client.data_classes import filters\nin_timezone = filters.Prefix([\"metadata\", \"timezone\"], \"Europe\")\nres = client.assets.list(advanced_filter=in_timezone, sort=(\"external_id\", \"asc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.assets import AssetProperty, SortableAssetProperty\nin_timezone = filters.Prefix(AssetProperty.metadata_key(\"timezone\"), \"Europe\")\nres = client.assets.list(\n advanced_filter=in_timezone,\n sort=(SortableAssetProperty.external_id, \"asc\"))\n\nfrom cognite.client.data_classes import filters\nnot_instrument_lvl5 = filters.And(\n filters.ContainsAny(\"labels\", [\"Level5\"]),\n filters.Not(filters.ContainsAny(\"labels\", [\"Instrument\"]))\n)\nres = client.assets.list(asset_subtree_ids=[123456], advanced_filter=not_instrument_lvl5)\n"
- lang: Java
label: Java SDK
source: "List<Asset> listAssetsResults = new ArrayList<>(); \nclient.assets() \n .list() \n .forEachRemaining(listAssetsResults::addAll); \n\n \nclient.assets() \n .list(Request.create() \n .withFilterParameter(\"source\", \"source\")) \n .forEachRemaining(listAssetsResults::addAll); \n\n"
/assets/aggregate:
post:
tags:
- Assets
summary: Aggregate assets
description: '
> **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.'
operationId: aggregateAssets
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AssetAggregateRequest'
responses:
'200':
$ref: '#/components/responses/AggregateResponse'
'400':
$ref: '#/components/responses/400ErrorResponse'
'429':
$ref: '#/components/responses/429ErrorResponse'
x-capability:
- assetsAcl:READ
x-code-samples:
- lang: JavaScript
label: JavaScript SDK
source: 'const aggregates = await client.assets.aggregate({ filter: { root: true } });
console.log(''Number of root assets: '', aggregates[0].count)'
- lang: Python
label: Python SDK
source: "aggregate_by_prefix = client.assets.aggregate(filter={\"external_id_prefix\": \"prefix\"})\nfrom cognite.client.data_classes.assets import AssetProperty\nkey_count = client.assets.aggregate_cardinality_properties(AssetProperty.metadata)\nfrom cognite.client.data_classes.assets import AssetProperty\nlabel_count = client.assets.aggregate_cardinality_values(AssetProperty.labels)\n\nfrom cognite.client.data_classes.filters import Search\nfrom cognite.client.data_classes.assets import AssetProperty\nis_critical = Search(AssetProperty.description, \"critical\")\ncritical_assets = client.assets.aggregate_cardinality_values(\n AssetProperty.metadata_key(\"timezone\"),\n advanced_filter=is_critical)\ncount = client.assets.aggregate_count()\n\nfrom cognite.client.data_classes.filters import ContainsAny\nfrom cognite.client.data_classes.assets import AssetProperty\nhas_timezone = ContainsAny(AssetProperty.metadata, \"timezone\")\nasset_count = client.assets.aggregate_count(advanced_filter=has_timezone)\nfrom cognite.client.data_classes.assets import AssetProperty\nresult = client.assets.aggregate_unique_properties(AssetProperty.metadata)\nfrom cognite.client.data_classes.assets import AssetProperty\nresult = client.assets.aggregate_unique_values(AssetProperty.metadata_key(\"timezone\"))\nprint(result.unique)\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.assets import AssetProperty\nfrom cognite.client.utils import timestamp_to_ms\nfrom datetime import datetime\ncreated_after_2020 = filters.Range(AssetProperty.created_time, gte=timestamp_to_ms(datetime(2
# --- truncated at 32 KB (111 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cognite/refs/heads/main/openapi/cognite-assets-api-openapi.yml