Filter events

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

Advanced filtering

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

See the advancedFilter attribute in the example.

See more information about filtering DSL here.

Supported leaf filters

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

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

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

advancedFilter attribute limits

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

Sorting

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

See the sort attribute in the example.

Null values

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

Sorting by score

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

"advancedFilter" : {
  "or" : [
    {
      "equals": {
        "property": ["type"], 
        "value": "fire"
      }
    },
    {
      "prefix": {
        "property": ["type"], 
        "value": "fire"
      }
    }
  ]
},
"sort": [
  {
    "property" : ["_score_"]
  }
]

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.

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

Filter on events filter with exact match

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

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

See more information about filtering DSL here.

Supported properties:

Property Type
["assetIds"] array of [number]
["createdTime"] number
["dataSetId"] number
["endTime"] number
["id"] number
["lastUpdatedTime"] number
["startTime"] number
["description"] string
["externalId"] string
["metadata"] string
["metadata", "someCustomKey"] string
["source"] string
["subtype"] string
["type"] string

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

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

Limits the maximum number of results to be returned by a single request. In case there are more results to the request, the 'nextCursor' attribute will be provided as part of the response. Request may contain less results than the request limit.

Array of modern (objects) or Array of deprecated (strings)
cursor
string
partition
string (PartitionLimited10)

Splits the data set into N partitions. The attribute is specified as a "M/N" string, where M is a natural number in the interval of [1, N]. You need to follow the cursors within each partition in order to receive all the data.

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

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

Responses
200

Paged response with list of events

400

The response for a bad request.

429

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

post/events/list
Request samples
application/json
{
  • "filter": {
    • "startTime": {
      },
    • "endTime": {
      },
    • "activeAtTime": {
      },
    • "metadata": {
      },
    • "assetIds": [
      ],
    • "assetExternalIds": [
      ],
    • "assetSubtreeIds": [
      ],
    • "dataSetIds": [
      ],
    • "source": "string",
    • "type": "string",
    • "subtype": "string",
    • "createdTime": {
      },
    • "lastUpdatedTime": {
      },
    • "externalIdPrefix": "my.known.prefix"
    },
  • "advancedFilter": {
    • "or": [
      ]
    },
  • "limit": 100,
  • "sort": [
    • {
      },
    • {
      }
    ],
  • "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
  • "partition": "1/3"
}
Response samples
application/json
{
  • "items": [
    • {
      }
    ],
  • "nextCursor": "string"
}