openapi: 3.1.0
info:
title: Cognite 3D Asset Mapping Events 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: Events
description: "Events objects store complex information about multiple assets over a time period.\nTypical types of events that would be stored in this service might include Alarms, Process Data, and Logs.\\\nFor the storage of low volume, manually generated, schedulable activities (such as maintenance schedules,\nwork orders or other â\x80\x98appointmentâ\x80\x99 type activities, the Data Modeling service is now recommended.\n\n#### Important Note:\nEvents and Time Series are somewhat closely related in that both are high volume types of data,\ncapable of recording data in microsecond resolutions. However, Events is not recommended as a Time Series store,\nsuch as where the data flow is from a single instance of sensors (i.e. temperature, pressure, voltage),\nsimulators or state machines (on, off, disconnected, etc).\\\nTime Series offers very low latency read and write performance, as well as specialised filters and aggregations that\nare tailored to the analysis of time series data.\n\nAn eventâ\x80\x99s time period is defined by a start time and end time, both millisecond timestamps since the UNIX epoch.\nThe timestamps can be in the future. In addition, events can have a text description as well as arbitrary metadata and properties.\\\nWhen storing event information in metadata, it should be considered that all data is stored as string format.\n\n#### Note:\nIn Events API, timestamps are treated as strings when added to\nmetadata fields and arenâ\x80\x99t converted to the userâ\x80\x99s local time zone.\n\n**Caveats:**\\\nDue to the eventually consistent nature of Asset IDs stored in Events,\nit should be noted that Asset ID references obtained from the Events API may\noccasionally be invalid (such as if an Asset ID is deleted,\nbut the reference to that ID remains in the Event record for a time).\n\nAsset references obtained from an event - through asset ids - may be\ninvalid, simply by the non-transactional nature of HTTP.\nThey are maintained in an eventual consistent manner.\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/EventsLimitsNov23.png\" alt=\" \" width=\"80%\"/>\n\n### Translating RPS into data speed\nA single request may retrieve up to 1000 items. In the context of Events, 1 item = 1 event 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 Events 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:
/events:
post:
tags:
- Events
summary: Create events
description: '
> **Required capabilities:** `eventsAcl:WRITE`
Creates multiple event objects in the same project.
It is possible to post a maximum of 1000 events per request.
### Request throttling
This endpoint is a subject of the new throttling schema (limited request rate and concurrency).
Please check [Events resource description](../../) for more information.'
operationId: createEvents
requestBody:
description: List of events to be posted. It is possible to post a maximum of 1000 events per request.
content:
application/json:
schema:
$ref: '#/components/schemas/DataExternalEvent'
required: true
responses:
'201':
$ref: '#/components/responses/EventDataResponse'
'400':
$ref: '#/components/responses/400ErrorResponse'
'429':
$ref: '#/components/responses/429ErrorResponse'
x-capability:
- eventsAcl:WRITE
x-code-samples:
- lang: JavaScript
label: JavaScript SDK
source: "const events = [\n { description: 'Workorder pump abc', startTime: new Date('22 jan 2019') },\n { description: 'Broken rule', externalId: 'rule123', startTime: 1557346524667000 },\n];\nconst createdEvents = await client.events.create(events);"
- lang: Python
label: Python SDK
source: 'from cognite.client.data_classes import EventWrite
events = [EventWrite(start_time=0, end_time=1), EventWrite(start_time=2, end_time=3)]
res = client.events.create(events)
'
- lang: Java
label: Java SDK
source: "List<Event> upsertEventsList = List.of(Event.newBuilder() \n .setExternalId(\"10\") \n .setStartTime(1552566113) \n .setEndTime(1553566113) \n .setDescription(\"generated_event_\") \n .setType(\"generated_event\") \n .setSubtype(\"event_sub_type\") \n .setSource(\"sdk-data-generator\") \n .putMetadata(\"type\", \"sdk-data-generator\") \n .build()); \nclient.events().upsert(upsertEventsList); \n\n "
get:
tags:
- Events
summary: List events
description: '
> **Required capabilities:** `eventsAcl:READ`
List events optionally filtered on query parameters
### Request throttling
This endpoint is meant for data analytics/exploration usage and is not suitable for high load data retrieval usage.
It is a subject of the new throttling schema (limited request rate and concurrency).
Please check [Events resource description](../../) for more information.'
operationId: listEvents
parameters:
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Cursor'
- in: query
name: minStartTime
schema:
$ref: '#/components/schemas/EpochTimestamp'
- in: query
name: maxStartTime
schema:
$ref: '#/components/schemas/EpochTimestamp'
- in: query
name: minEndTime
schema:
$ref: '#/components/schemas/EpochTimestamp'
- in: query
name: maxEndTime
schema:
$ref: '#/components/schemas/EpochTimestamp'
- in: query
name: minActiveAtTime
schema:
description: 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.
allOf:
- $ref: '#/components/schemas/EpochTimestamp'
- in: query
name: maxActiveAtTime
schema:
description: 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.
allOf:
- $ref: '#/components/schemas/EpochTimestamp'
- in: query
name: assetIds
description: Asset IDs of equipment that this event relates to. Format is list of IDs serialized as JSON array(int64). Takes [ 1 .. 100 ] of unique items.
example: '[363848954441724, 793045462540095, 1261042166839739]'
schema:
$ref: '#/components/schemas/JsonArrayInt64'
- in: query
name: assetExternalIds
description: Asset external IDs of equipment that this event relates to. Takes 1..100 unique items.
example: '["externalId1", "externalId2", "externalId3"]'
schema:
$ref: '#/components/schemas/JsonArrayString'
- in: query
name: assetSubtreeIds
description: Only include events that have a related asset in a subtree rooted at any of these assetIds (including the roots given). If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.
example: '[363848954441724, 793045462540095, 1261042166839739]'
schema:
$ref: '#/components/schemas/JsonArrayInt64'
- in: query
name: assetSubtreeExternalIds
description: Only include events that have a related asset in a subtree rooted at any of these assetExternalIds (including the roots given). If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.
example: '["externalId1", "externalId2", "externalId3"]'
schema:
$ref: '#/components/schemas/JsonArrayString'
- in: query
name: source
schema:
maxLength: 128
type: string
description: The source of this event.
- in: query
name: type
schema:
$ref: '#/components/schemas/EventType'
- in: query
name: subtype
schema:
$ref: '#/components/schemas/EventSubType'
- 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'
style: form
explode: false
- $ref: '#/components/parameters/partitionLimited10'
- $ref: '#/components/parameters/IncludeMetadata'
- in: query
name: sort
description: "Sort by an array of the selected fields. Syntax: `[\"<fieldname>:asc|desc\"]`. Default sort order is `asc` with short syntax: `[\"<fieldname>\"]`.\nFilter accepts the following field names:\n `dataSetId`,\n `externalId`,\n `type`,\n `subtype`,\n `startTime`,\n `endTime`,\n `createdTime`,\n `lastUpdatedTime`,\n `source`,\n `description`,\n `metadata`.\nPartitions are done independently of sorting, there's no guarantee on sort order between elements from different partitions.\n"
example:
- endTime:desc
schema:
type: array
items:
type: string
responses:
'200':
$ref: '#/components/responses/EventDataWithCursorResponse'
'400':
$ref: '#/components/responses/400ErrorResponse'
'429':
$ref: '#/components/responses/429ErrorResponse'
x-capability:
- eventsAcl:READ
x-code-samples:
- lang: JavaScript
label: JavaScript SDK
source: 'const events = await client.events.list({ filter: { startTime: { min: new Date(''1 jan 2018'') }, endTime: { max: new Date(''1 jan 2019'') } } });'
- lang: Python
label: Python SDK
source: "from cognite.client.data_classes import filters\nis_workorder = filters.Prefix(\"external_id\", \"workorder\")\nhas_failure = filters.Search(\"description\", \"failure\")\nres = client.events.filter(\n filter=filters.And(is_workorder, has_failure), sort=(\"start_time\", \"desc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.events import EventProperty, SortableEventProperty\nis_workorder = filters.Prefix(EventProperty.external_id, \"workorder\")\nhas_failure = filters.Search(EventProperty.description, \"failure\")\nres = client.events.filter(\n filter=filters.And(is_workorder, has_failure),\n sort=(SortableEventProperty.start_time, \"desc\"))\nevent_list = client.events.list(limit=5, start_time={\"max\": 1500000000})\n\nfor event in client.events:\n event # do something with the event\n\nfor event_list in client.events(chunk_size=2500):\n event_list # do something with the events\n\nfrom cognite.client.data_classes import filters\nin_timezone = filters.Prefix([\"metadata\", \"timezone\"], \"Europe\")\nres = client.events.list(advanced_filter=in_timezone, sort=(\"external_id\", \"asc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.events import EventProperty, SortableEventProperty\nin_timezone = filters.Prefix(EventProperty.metadata_key(\"timezone\"), \"Europe\")\nres = client.events.list(\n advanced_filter=in_timezone,\n sort=(SortableEventProperty.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.events.list(asset_subtree_ids=[123456], advanced_filter=not_instrument_lvl5)\n"
/events/{id}:
get:
tags:
- Events
summary: Receive an event by its ID
description: '
> **Required capabilities:** `eventsAcl:READ`
Retrieves an event by its internal (service-generated) ID.
### Request throttling
This endpoint is a subject of the new throttling schema (limited request rate and concurrency).
Please check [Events resource description](../../) for more information.'
operationId: getEventByInternalId
parameters:
- in: path
name: id
required: true
schema:
$ref: '#/components/schemas/CogniteInternalId'
responses:
'200':
$ref: '#/components/responses/EventResponse'
'400':
$ref: '#/components/responses/400ErrorResponse'
'429':
$ref: '#/components/responses/429ErrorResponse'
x-capability:
- eventsAcl:READ
x-code-samples:
- lang: JavaScript
label: JavaScript SDK
source: 'const events = await client.events.retrieve([{id: 123}, {externalId: ''abc''}]);'
- lang: Python
label: Python SDK
source: 'res = client.events.retrieve(id=1)
res = client.events.retrieve(external_id="1")
'
/events/list:
post:
tags:
- Events
summary: Filter events
description: "\n\n> **Required capabilities:** `eventsAcl:READ`\n\nRetrieve a list of events in the same project. This operation supports pagination by cursor.\nApply Filtering and Advanced filtering criteria to select a subset of events.\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| 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` | `[\"description\"]` | Introduced to provide functional parity with /events/search endpoint. <br /> `{\"search\": {\"property\": [\"property\"], \"value\": \"example\"}}` |\n\n##### Search\nThe `search` leaf filter provides functional parity with the `/events/search` endpoint.\nIt's available only for the `[\"description\"]` field. When specifying only this filter with no explicit ordering,\nbehavior is the same as of the `/events/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- filter by metadata is case-insensitive, and it supports filtering on keys and values up to 256 characters\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 For metadata, both upper and lower 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 - `description` - 128 for the `search` filter and 255 for other filters\n - `type` - 64\n - `subtype` - 64\n - `source` - 128\n - any `metadata` key - 128\n\n### Sorting\nBy default, events are sorted by their creation time 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 and defaults\nto `desc` for `_score_` and `asc` for all other fields.\nThe `nulls` field is optional and defaults to `auto`. `auto` is translated to `last`\nfor 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 event 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 event with the type `fire` will match both `equals` and `prefix`\nfilters and, therefore, have higher score than events with names like `fire training` that match only the `prefix` filter.\n\n```\n\"advancedFilter\" : {\n \"or\" : [\n {\n \"equals\": {\n \"property\": [\"type\"],\n \"value\": \"fire\"\n }\n },\n {\n \"prefix\": {\n \"property\": [\"type\"],\n \"value\": \"fire\"\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 [Events resource description](../../) for more information."
operationId: advancedListEvents
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EventFilterRequest'
responses:
'200':
$ref: '#/components/responses/EventDataWithCursorResponse'
'400':
$ref: '#/components/responses/400ErrorResponse'
'429':
$ref: '#/components/responses/429ErrorResponse'
x-capability:
- eventsAcl:READ
x-code-samples:
- lang: JavaScript
label: JavaScript SDK
source: 'const events = await client.events.list({ filter: { startTime: { min: new Date(''1 jan 2018'') }, endTime: { max: new Date(''1 jan 2019'') } } });'
- lang: Python
label: Python SDK
source: "from cognite.client.data_classes import filters\nis_workorder = filters.Prefix(\"external_id\", \"workorder\")\nhas_failure = filters.Search(\"description\", \"failure\")\nres = client.events.filter(\n filter=filters.And(is_workorder, has_failure), sort=(\"start_time\", \"desc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.events import EventProperty, SortableEventProperty\nis_workorder = filters.Prefix(EventProperty.external_id, \"workorder\")\nhas_failure = filters.Search(EventProperty.description, \"failure\")\nres = client.events.filter(\n filter=filters.And(is_workorder, has_failure),\n sort=(SortableEventProperty.start_time, \"desc\"))\nevent_list = client.events.list(limit=5, start_time={\"max\": 1500000000})\n\nfor event in client.events:\n event # do something with the event\n\nfor event_list in client.events(chunk_size=2500):\n event_list # do something with the events\n\nfrom cognite.client.data_classes import filters\nin_timezone = filters.Prefix([\"metadata\", \"timezone\"], \"Europe\")\nres = client.events.list(advanced_filter=in_timezone, sort=(\"external_id\", \"asc\"))\n\nfrom cognite.client.data_classes import filters\nfrom cognite.client.data_classes.events import EventProperty, SortableEventProperty\nin_timezone = filters.Prefix(EventProperty.metadata_key(\"timezone\"), \"Europe\")\nres = client.events.list(\n advanced_filter=in_timezone,\n sort=(SortableEventProperty.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.events.list(asset_subtree_ids=[123456], advanced_filter=not_instrument_lvl5)\n"
- lang: Java
label: Java SDK
source: "List<Event> listEventsResults = new ArrayList<>(); \nclient.events() \n .list() \n .forEachRemaining(events -> listEventsResults.addAll(events)); \n\nclient.events() \n .list(Request.create() \n .withFilterParameter(\"source\", \"source\")) \n .forEachRemaining(events -> listEventsResults.addAll(events)); \n\n"
/events/aggreg
# --- truncated at 32 KB (105 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cognite/refs/heads/main/openapi/cognite-events-api-openapi.yml