Cognite Sequences API

openapi: 3.1.0
info:
  title: Cognite 3D Asset Mapping Sequences 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: Sequences
  description: 'A sequence stores a table with up to 400 columns indexed by row number. There can be at most 400 numeric columns and 200 string columns. Each of the columns has a pre-defined type: a string, integer, or floating point number.


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

    To learn more about sequences, see the [concept guide](https://docs.cognite.com/dev/concepts/resource_types/sequences).

    '
paths:
  /sequences:
    get:
      tags:
      - Sequences
      summary: List sequences
      operationId: listSequences
      description: '


        > **Required capabilities:** `sequencesAcl:READ`


        List sequences. Use `nextCursor` to paginate through the results.'
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/partition'
      - in: query
        name: limit
        description: Limits the number of results to be returned. The server returns a maximum of 1000 results even if you specify a higher limit.
        schema:
          type: integer
          default: 25
          minimum: 1
          maximum: 1000
      responses:
        '200':
          description: Paged response with a list of sequences.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SequenceWithCursorResponse'
      x-capability:
      - sequencesAcl:READ
      x-code-samples:
      - lang: JavaScript
        label: JavaScript SDK
        source: 'const sequences = await client.sequences.list({ filter: { name: ''sequence_name'' } });'
      - lang: Python
        label: Python SDK
        source: "from cognite.client.data_classes import filters\nasset_filter = filters.Equals(\"asset_id\", 123)\nis_efficiency = filters.Equals([\"metadata\", \"type\"], \"efficiency\")\nres = client.sequences.filter(filter=filters.And(asset_filter, is_efficiency), sort=\"created_time\")\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.sequences import SequenceProperty, SortableSequenceProperty\nasset_filter = filters.Equals(SequenceProperty.asset_id, 123)\nis_efficiency = filters.Equals(SequenceProperty.metadata_key(\"type\"), \"efficiency\")\nres = client.sequences.filter(\n    filter=filters.And(asset_filter, is_efficiency),\n    sort=SortableSequenceProperty.created_time)\nres = client.sequences.list(limit=5)\n\nfor seq in client.sequences:\n    seq # do something with the sequence\n\nfor seq_list in client.sequences(chunk_size=2500):\n    seq_list # do something with the sequences\n\nfrom cognite.client.data_classes import filters\nin_timezone = filters.Prefix([\"metadata\", \"timezone\"], \"Europe\")\nres = client.sequences.list(advanced_filter=in_timezone, sort=(\"external_id\", \"asc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.sequences import SequenceProperty, SortableSequenceProperty\nin_timezone = filters.Prefix(SequenceProperty.metadata_key(\"timezone\"), \"Europe\")\nres = client.sequences.list(\n    advanced_filter=in_timezone,\n    sort=(SortableSequenceProperty.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.sequences.list(asset_subtree_ids=[123456], advanced_filter=not_instrument_lvl5)\n"
    post:
      tags:
      - Sequences
      summary: Create sequences
      description: '


        > **Required capabilities:** `sequencesAcl:WRITE`


        Create one or more sequences.'
      operationId: createSequence
      requestBody:
        description: Sequence to be stored.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataPostSequence'
      responses:
        '201':
          description: Response with the created sequence.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataGetSequence'
        '400':
          $ref: '#/components/responses/ErrorResponse'
      x-capability:
      - sequencesAcl:WRITE
      x-code-samples:
      - lang: JavaScript
        label: JavaScript SDK
        source: "const sequences = [\n {\n  externalId: 'sequence_name',\n  columns: [\n   {\n     externalId: 'one',\n     valueType: SequenceValueType.LONG,\n   },\n   {\n     externalId: 'two',\n   },\n   {\n     externalId: 'three',\n     valueType: SequenceValueType.STRING,\n   }\n  ]\n }\n];\nconst [sequence] = await client.sequences.create(sequences);"
      - lang: Python
        label: Python SDK
        source: "from cognite.client.data_classes import SequenceWrite, SequenceColumnWrite\ncolumn_def = [\n    SequenceColumnWrite(value_type=\"String\", external_id=\"user\", description=\"some description\"),\n    SequenceColumnWrite(value_type=\"Double\", external_id=\"amount\")\n]\nseq = client.sequences.create(SequenceWrite(external_id=\"my_sequence\", columns=column_def))\n\nseq2 = client.sequences.create(SequenceWrite(external_id=\"my_copied_sequence\", columns=column_def))\n"
      - lang: Java
        label: Java SDK
        source: "List<SequenceColumn> columns = List.of(SequenceColumn.newBuilder() \n          .setExternalId(\"10\") \n          .setName(\"test_column_\") \n          .setDescription(\"Description\") \n          .setValueTypeValue(SequenceColumn.ValueType.STRING_VALUE) \n     .build()); \n\n List<SequenceMetadata> upsertSequencesList = List.of( SequenceMetadata.newBuilder() \n          .setExternalId(\"10\") \n          .setName(\"test_sequence_\") \n          .setDescription(\"Description\") \n          .putMetadata(\"type\", \"sdk-data-generator\") \n          .addAllColumns(columns) \n     .build()); \n\n client.sequences().upsert(upsertSequencesList); \n\n"
  /sequences/list:
    post:
      tags:
      - Sequences
      summary: Filter sequences
      description: "\n\n> **Required capabilities:** `sequencesAcl:READ`\n\n<details>\n<summary>\nRetrieves a list of sequences that match the given criteria.\n</summary>\n\n### Advanced filtering\n\nThe `advancedFilter`\nfield lets you create complex filtering expressions that combine simple operations,\nsuch as `equals`, `prefix`, and `exists`, by using the Boolean operators `and`, `or`, and `not`.\nFiltering applies to basic fields as well as metadata. See the `advancedFilter` syntax in the request example.\n\n\n\n#### Supported leaf filters\n\n| Leaf filter    | Supported fields       | Description and example                                                                                                                                                            |\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 a 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 text. <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\"]` and `[\"description\"]` | Introduced to provide functional parity with the /sequences/search endpoint. <br /> `{\"search\": {\"property\": [\"property\"], \"value\": \"example\"}}`                        |\n\n#### Supported properties\n\n| Property                          | Type               |\n|-----------------------------------|--------------------|\n| `[\"description\"]`                 | string             |\n| `[\"externalId\"]`                  | string             |\n| `[\"metadata\", \"<someCustomKey>\"]` | string             |\n| `[\"name\"]`                        | string             |\n| `[\"assetId\"]`                      | number              |\n| `[\"assetRootId\"]`                  | number              |\n| `[\"createdTime\"]`                  | number              |\n| `[\"dataSetId\"]`                    | number              |\n| `[\"id\"]`                           | number              |\n| `[\"lastUpdatedTime\"]`              | number              |\n\n#### Limits\n\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 (and at most 99, since each element counts\n  towards the total clause limit, and so does the `and`/`or` clause itself).\n- The `property` array of each leaf filter has the following limitations:\n  - Number of elements in the array is 1 or 2.\n  - Elements must not be null or blank.\n  - Each element max length is 256 characters.\n  - The `property` array must match one of the existing properties (static top-level property or dynamic metadata property).\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 number or string type (matching the type of the given property).\n- `range` filter must have at lest one of `gt`, `gte`, `lt`, `lte` attributes.\n  But `gt` is mutually exclusive to `gte`, while `lt` is mutually exclusive to `lte`.\n- `gt`, `gte`, `lt`, `lte` in the `range` filter must be of number or string type (matching the type of the given property).\n- `search` filter `value` must not be blank, and the length must be in the range [1, 128], and there\n  may be at most two `search` filters in the entire filter query.\n- The maximum length of the `value` of a leaf filter that is applied to a string property is 256.\n\n### Sorting\n\nBy default, sequences are sorted by their creation time in ascending order.\nSorting by another property or by several other properties can be explicitly requested via the\n`sort` field, which must contain a list\nof one or more sort specifications. Each sort specification indicates the `property` to sort on\nand, optionally, the `order` in which to sort (defaults to `asc`). If multiple sort specifications are\nsupplied, the results are sorted on the first property, and those with the same value for the first\nproperty are sorted on the second property, and so on.  \nPartitioning is done independently of sorting; there is no guarantee of sort order between elements from different partitions.\n\n#### Null values\n\nIn case the `nulls` field has the `auto` value, or the field isn't specified, null (missing) values\nare considered bigger than any other values. They are placed last when sorting in the `asc`\norder and first in the `desc` order. Otherwise, missing values are placed according to\nthe `nulls` field (`last` or `first`), and their placement won't depend on the `order`\nfield. Note that the number zero, empty strings, and empty lists are all considered\n_not_ null.\n\n#### Example\n\n```json\n{\n  \"sort\": [\n    {\n      \"property\" : [\"createdTime\"],\n      \"order\": \"desc\",\n      \"nulls\": \"last\"\n    },\n    {\n      \"property\" : [\"metadata\", \"<someCustomKey>\"]\n    }\n  ]\n}\n```\n\n\n#### Properties\n\nYou can sort on the following properties:\n\n| Property                          |\n|-----------------------------------|\n| `[\"assetId\"]`                     |\n| `[\"createdTime\"]`                 |\n| `[\"dataSetId\"]`                   |\n| `[\"description\"]`                 |\n| `[\"externalId\"]`                  |\n| `[\"lastUpdatedTime\"]`             |\n| `[\"metadata\", \"<someCustomKey>\"]` |\n| `[\"name\"]`                        |\n\n#### Limits\n\nThe `sort` array must contain 1 to 2 elements.\n</details>\n"
      operationId: advancedListSequences
      requestBody:
        description: Retrieves a list of sequences matching the given criteria.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SequencesAdvancedListDTO'
      responses:
        '200':
          description: Response with a list of sequences matching the given criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SequenceWithCursorResponse'
      x-capability:
      - sequencesAcl:READ
      x-code-samples:
      - lang: JavaScript
        label: JavaScript SDK
        source: 'const sequences = await client.sequences.list({ filter: { name: ''sequence_name'' } });'
      - lang: Python
        label: Python SDK
        source: "from cognite.client.data_classes import filters\nasset_filter = filters.Equals(\"asset_id\", 123)\nis_efficiency = filters.Equals([\"metadata\", \"type\"], \"efficiency\")\nres = client.sequences.filter(filter=filters.And(asset_filter, is_efficiency), sort=\"created_time\")\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.sequences import SequenceProperty, SortableSequenceProperty\nasset_filter = filters.Equals(SequenceProperty.asset_id, 123)\nis_efficiency = filters.Equals(SequenceProperty.metadata_key(\"type\"), \"efficiency\")\nres = client.sequences.filter(\n    filter=filters.And(asset_filter, is_efficiency),\n    sort=SortableSequenceProperty.created_time)\nres = client.sequences.list(limit=5)\n\nfor seq in client.sequences:\n    seq # do something with the sequence\n\nfor seq_list in client.sequences(chunk_size=2500):\n    seq_list # do something with the sequences\n\nfrom cognite.client.data_classes import filters\nin_timezone = filters.Prefix([\"metadata\", \"timezone\"], \"Europe\")\nres = client.sequences.list(advanced_filter=in_timezone, sort=(\"external_id\", \"asc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.sequences import SequenceProperty, SortableSequenceProperty\nin_timezone = filters.Prefix(SequenceProperty.metadata_key(\"timezone\"), \"Europe\")\nres = client.sequences.list(\n    advanced_filter=in_timezone,\n    sort=(SortableSequenceProperty.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.sequences.list(asset_subtree_ids=[123456], advanced_filter=not_instrument_lvl5)\n"
      - lang: Java
        label: Java SDK
        source: "List<SequenceMetadata> listSequencesResults = new ArrayList<>(); \n client.sequences() \n          .list() \n          .forEachRemaining(sequences -> listSequencesResults.addAll(sequences)); \n\n client.sequences() \n          .list(Request.create() \n               .withFilterMetadataParameter(\"source\", \"sdk-data-generator\")) \n          .forEachRemaining(sequences -> listSequencesResults.addAll(sequences)); \n\n"
  /sequences/aggregate:
    post:
      tags:
      - Sequences
      summary: Aggregate sequences
      operationId: aggregateSequences
      x-capability:
      - sequencesAcl:READ
      description: "\n\n> **Required capabilities:** `sequencesAcl:READ`\n\nThe aggregation API allows you to compute aggregated results from a set of sequences, such as\r\ngetting the number of sequences in a project or checking what assets the different sequences\r\nin your project are associated with (along with the number of sequences for each asset).\r\nBy specifying `filter` and/or `advancedFilter`, the aggregation will take place only over those\r\nsequences that match the filters. `filter` and `advancedFilter` behave the same way as in the\r\n`list` endpoint.\r\n\r\n<details>\r\n<summary>\r\nThe default behavior, when the <code>aggregate</code> field is not specified the request body, is to return the\r\nnumber of sequences that match the filters (if any), which is the same behavior as when the\r\n<code>aggregate</code> field is set to <code>count</code>.\r\n</summary>\r\n\r\nThe following requests will both return the total number of\r\nsequences whose `name` begins with `pump`:\r\n\r\n```\r\n{\r\n  \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}}\r\n}\r\n```\r\n\r\nand\r\n\r\n```\r\n{\r\n  \"aggregate\": \"count\",\r\n  \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}}\r\n}\r\n```\r\n\r\nThe response might be:\r\n\r\n```\r\n{\"items\": [{\"count\": 42}]}\r\n```\r\n</details>\r\n\r\n<details>\r\n<summary>\r\nSetting <code>aggregate</code> to <code>uniqueValues</code> and specifying a property in <code>properties</code> (this field is an array, but currently only supports one property) will\r\nreturn all unique values (up to a maximum of 1000) that are taken on by that property\r\nacross all the sequences that match the filters, as well as the number of sequences that\r\nhave each of those property values.\r\n</summary>\r\n\r\nThis example request finds all the unique asset ids that are\r\nreferenced by the sequences in your project whose `name` begins with `pump`:\r\n\r\n```\r\n{\r\n  \"aggregate\": \"uniqueValues\",\r\n  \"properties\": [{\"property\": [\"assetId\"]}],\r\n  \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}}\r\n}\r\n```\r\n\r\nThe response might be the following, saying that 23 sequences are associated with asset 18\r\nand 107 sequences are associated with asset 76:\r\n\r\n```\r\n{\r\n  \"items\": [\r\n    {\"values\": [\"18\"], \"count\": 23},\r\n    {\"values\": [\"76\"], \"count\": 107}\r\n  ]\r\n}\r\n```\r\n</details>\r\n\r\n<details>\r\n<summary>\r\nSetting <code>aggregate</code> to <code>cardinalityValues</code> will instead return the approximate number of\r\ndistinct values that are taken on by the given property among the matching sequences.\r\n</summary>\r\n\r\nExample request:\r\n\r\n```\r\n{\r\n  \"aggregate\": \"cardinalityValues\",\r\n  \"properties\": [{\"property\": [\"assetId\"]}],\r\n  \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}}\r\n}\r\n```\r\n\r\nThe result is likely exact when the set of unique values is small. In this example, there are likely two distinct asset ids among the matching sequences:\r\n\r\n```\r\n{\"items\": [{\"count\": 2}]}\r\n```\r\n</details>\r\n\r\n<details>\r\n<summary>\r\nSetting <code>aggregate</code> to <code>uniqueProperties</code> will return the set of unique properties whose property\r\npath begins with <code>path</code> (which can currently only be <code>[\"metadata\"]</code>) that are contained in the sequences that match the filters.\r\n</summary>\r\n\r\nExample request:\r\n\r\n```\r\n{\r\n  \"aggregate\": \"uniqueProperties\",\r\n  \"path\": [\"metadata\"],\r\n  \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}}\r\n}\r\n```\r\n\r\nThe result contains all the unique metadata keys in the sequences whose `name` begins with\r\n`pump`, and the number of sequences that contains each metadata key:\r\n\r\n```\r\n{\r\n  \"items\": [\r\n    {\"values\": [{\"property\": [\"metadata\", \"tag\"]}], \"count\": 43},\r\n    {\"values\": [{\"property\": [\"metadata\", \"installationDate\"]}], \"count\": 97}\r\n  ]\r\n}\r\n```\r\n</details>\r\n\r\n<details>\r\n<summary>\r\nSetting <code>aggregate</code> to <code>cardinalityProperties</code> will instead return the approximate number of\r\ndifferent property keys whose path begins with <code>path</code> (which can currently only be <code>[\"metadata\"]</code>, meaning that this can only be used to count the approximate number of distinct metadata keys among the matching sequences).\r\n</summary>\r\n\r\nExample request:\r\n\r\n```\r\n{\r\n  \"aggregate\": \"cardinalityProperties\",\r\n  \"path\": [\"metadata\"],\r\n  \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}}\r\n}\r\n```\r\n\r\nThe result is likely exact when the set of unique values is small. In this example, there are likely two distinct metadata keys among the matching sequences:\r\n\r\n```\r\n{\"items\": [{\"count\": 2}]}\r\n```\r\n</details>\r\n\r\nThe `aggregateFilter` field may be specified if `aggregate` is set to `cardinalityProperties` or `uniqueProperties`. The structure of this field is similar to that of `advancedFilter`, except that the set of leaf filters is smaller (`in`, `prefix`, and `range`), and that none of the leaf filters specify a property. Unlike `advancedFilter`, which is applied _before_ the aggregation (in order to restrict the set of sequences that the aggregation operation should be applied to), `aggregateFilter` is applied _after_ the initial aggregation has been performed, in order to restrict the set of results.\r\n\r\n<details>\r\n<summary>\r\nClick here for more details about <code>aggregateFilter</code>. \r\n</summary>\r\n\r\nWhen `aggregate` is set to `uniqueProperties`, the result set contains a number of _property paths_, each with an associated count that shows how many sequences contained that property (among those sequences that matched the `filter` and `advancedFilter`, if they were specified) . If `aggregateFilter` is specified, it will restrict the property paths included in the output. Let us add an `aggregateFilter` to the `uniqueProperties` example from above:\r\n\r\n```\r\n{\r\n  \"aggregate\": \"uniqueProperties\",\r\n  \"path\": [\"metadata\"],\r\n  \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}},\r\n  \"aggregateFilter\": {\"prefix\": {\"value\": \"t\"}}\r\n}\r\n```\r\n\r\nNow, 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):\r\n\r\n```\r\n{\r\n  \"items\": [\r\n    {\"values\": [{\"property\": [\"metadata\", \"tag\"]}], \"count\": 43}\r\n  ]\r\n}\r\n```\r\n\r\nSimilarly, adding `aggregateFilter` to `cardinalityProperties` will return the approximate number of properties whose property key matches `aggregateFilter` from those sequences matching the `filter` and `advancedFilter` (or from all sequences if neither `filter` nor `aggregateFilter` are specified):\r\n\r\n```\r\n{\r\n  \"aggregate\": \"cardinalityProperties\",\r\n  \"path\": [\"metadata\"],\r\n  \"advancedFilter\": {\"prefix\": {\"property\": [\"name\"], \"value\": \"pump\"}},\r\n  \"aggregateFilter\": {\"prefix\": {\"value\": \"t\"}}\r\n}\r\n```\r\n\r\nAs we saw above, only one property matches:\r\n\r\n```\r\n{\"items\": [{\"count\": 1}]}\r\n```\r\n\r\nNote 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`.\r\n</details>\r\n\r\n### Rate and concurrency limits\r\n\r\nRate and concurrency limits apply this endpoint. If a request exceeds one of the limits,\r\nit will be throttled with a `429: Too Many Requests` response. More on limit types\r\nand how to avoid being throttled is described\r\n[here](https://docs.cognite.com/dev/concepts/resource_throttling).\r\n\r\n| Limit          | Per project           | Per user (identity)   |\r\n|----------------|-----------------------|-----------------------|\r\n| Rate           | 15 requests per second| 10 requests per second|\r\n| Concurrency    | 6 concurrent requests | 4 concurrent requests |\r\n"
      requestBody:
        description: Aggregates the sequences that match the given criteria.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SequencesAdvancedAggregateDTO'
      responses:
        '200':
          description: Response with the aggregated sequences. The type of the response depends on the value of the `aggregate` parameter in the request.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/SequencesCountAggregateResponse'
                - $ref: '#/components/schemas/SequencesCardinalityValuesAggregateResponse'
                - $ref: '#/components/schemas/SequencesCardinalityPropertiesAggregateResponse'
                - $ref: '#/components/schemas/SequencesUniqueValuesAggregateResponse'
                - $ref: '#/components/schemas/SequencesUniquePropertiesAggregateResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
      x-code-samples:
      - lang: JavaScript
        label: JavaScript SDK
        source: 'const aggregates = await client.sequences.aggregate({ filter: { name: "Well" } });

          console.log(''Number of sequences named Well: '', aggregates[0].count)'
      - lang: Python
        label: Python SDK
        source: "res = client.sequences.aggregate(filter={\"external_id_prefix\": \"prefix\"})\nfrom cognite.client.data_classes.sequences import SequenceProperty\ncount = client.sequences.aggregate_cardinality_values(SequenceProperty.metadata)\nfrom cognite.client.data_classes.sequences import SequenceProperty\ncount = client.sequences.aggregate_cardinality_values(SequenceProperty.metadata_key(\"efficiency\"))\n\nfrom cognite.client.data_classes import filters, aggregations as aggs\nfrom cognite.client.data_classes.sequences import SequenceProperty\nnot_ameri

# --- truncated at 32 KB (117 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cognite/refs/heads/main/openapi/cognite-sequences-api-openapi.yml