List events

List events.

Parameters:

start_time (dict[str, Any] | TimestampRange | None) – Range between two timestamps.
end_time (dict[str, Any] | EndTimeFilter | None) – Range between two timestamps.
active_at_time (dict[str, Any] | TimestampRange | None) – 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.
type (str | None) – Type of the event, e.g ‘failure’.
subtype (str | None) – Subtype of the event, e.g ‘electrical’.
metadata (dict[str, str] | None) – Customizable extra data about the event. String key -> String value.
asset_ids (Sequence[int] | None) – Asset IDs of related equipments that this event relates to.
asset_external_ids (SequenceNotStr[str] | None) – Asset External IDs of related equipment that this event relates to.
asset_subtree_ids (int | Sequence[int] | None) – Only include events that have a related asset in a subtree rooted at any of these assetIds. If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.
asset_subtree_external_ids (str | SequenceNotStr[str] | None) – Only include events that have a related asset 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.
data_set_ids (int | Sequence[int] | None) – Return only events in the specified data set(s) with this id / these ids.
data_set_external_ids (str | SequenceNotStr[str] | None) – Return only events in the specified data set(s) with this external id / these external ids.
source (str | None) – The source of this event.
created_time (dict[str, Any] | TimestampRange | None) – Range between two timestamps. Possible keys are min and max, with values given as time stamps in ms.
last_updated_time (dict[str, Any] | TimestampRange | None) – Range between two timestamps. Possible keys are min and max, with values given as time stamps in ms.
external_id_prefix (str | None) – External Id provided by client. Should be unique within the project.
sort (SortSpec | list[SortSpec] | None) – The criteria to sort by. Defaults to desc for _score_ and asc for all other properties. Sort is not allowed if partitions is used.
partitions (int | None) – Retrieve resources in parallel using this number of workers (values up to 10 allowed), limit must be set to None (or -1).
limit (int | None) – Maximum number of events to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.
advanced_filter (Filter | dict[str, Any] | None) – Advanced filter query using the filter DSL (Domain Specific Language). It allows defining complex filtering expressions that combine simple operations, such as equals, prefix, exists, etc., using boolean operators and, or, and not. See examples below for usage.

Returns:

List of requested events

Return type:

EventList

Note

When using partitions, there are few considerations to keep in mind:

limit has to be set to None (or -1).
API may reject requests if you specify more than 10 partitions. When Cognite enforces this behavior, the requests result in a 400 Bad Request status.
Partitions are done independently of sorting: there’s no guarantee of the sort order between elements from different partitions. For this reason providing a sort parameter when using partitions is not allowed.

Examples

List events and filter on max start time:

>>> from cognite.client import CogniteClient, AsyncCogniteClient
>>> client = CogniteClient()
>>> # async_client = AsyncCogniteClient()  # another option
>>> event_list = client.events.list(limit=5, start_time={"max": 1500000000})

Iterate over events, one-by-one:

>>> for event in client.events():
...     event  # do something with the event

Iterate over chunks of events to reduce memory load:

>>> for event_list in client.events(chunk_size=2500):
...     event_list  # do something with the events

Using advanced filter, find all events that have a metadata key ‘timezone’ starting with ‘Europe’, and sort by external id ascending:

>>> from cognite.client.data_classes import filters
>>> in_timezone = filters.Prefix(["metadata", "timezone"], "Europe")
>>> res = client.events.list(advanced_filter=in_timezone, sort=("external_id", "asc"))

Note that you can check the API documentation above to see which properties you can filter on with which filters.

To make it easier to avoid spelling mistakes and easier to look up available properties for filtering and sorting, you can also use the EventProperty and SortableEventProperty Enums.

>>> from cognite.client.data_classes import filters
>>> from cognite.client.data_classes.events import EventProperty, SortableEventProperty
>>> in_timezone = filters.Prefix(EventProperty.metadata_key("timezone"), "Europe")
>>> res = client.events.list(
...     advanced_filter=in_timezone, sort=(SortableEventProperty.external_id, "asc")
... )

Combine filter and advanced filter:

>>> from cognite.client.data_classes import filters
>>> not_instrument_lvl5 = filters.And(
...     filters.ContainsAny("labels", ["Level5"]),
...     filters.Not(filters.ContainsAny("labels", ["Instrument"])),
... )
>>> res = client.events.list(
...     asset_subtree_ids=[123456], advanced_filter=not_instrument_lvl5
... )