# Events

An event marks a moment or interval in test data that someone should see, such as an engine start or an out-of-limit reading.
Events can come from people reviewing data, from [checklists](https://dev.nominal.io/python/guides/checklists/authoring.md) or from your scripts.

## Connect the client

This guide assumes you have [installed](https://dev.nominal.io/python/guides/install.md) the client and setup your [API keys](https://dev.nominal.io/python/guides/api-keys-setup.md).

```python
from nominal.core import NominalClient

client = NominalClient.from_profile("default")
```

## Create an event

Create an event on an [asset](https://dev.nominal.io/python/guides/assets.md) with [`create_event()`](https://dev.nominal.io/python/ref/generated/nominal.core.Asset.md#nominal.core.Asset.create_event "nominal.core.Asset.create_event").
A zero `duration`, the default, marks a single moment.

```python
from datetime import datetime, timedelta, timezone

from nominal.core import EventType

asset = client.get_asset("<ASSET_RID>")
event = asset.create_event(
    "Engine start",
    EventType.INFO,
    start=datetime.now(timezone.utc),
    duration=timedelta(seconds=10),
    properties={"test_phase": "burn"},
    labels=["critical"],
)
```

[`EventType`](https://dev.nominal.io/python/ref/generated/nominal.core.EventType.md#nominal.core.EventType "nominal.core.EventType") is the event’s level: `INFO`, `FLAG`, `ERROR` or `SUCCESS`.
To create an event on several assets, or on none, use [`create_event()`](https://dev.nominal.io/python/ref/generated/nominal.core.NominalClient.md#nominal.core.NominalClient.create_event "nominal.core.NominalClient.create_event") with `assets=[...]`.
[`create_event()`](https://dev.nominal.io/python/ref/generated/nominal.core.Run.md#nominal.core.Run.create_event "nominal.core.Run.create_event") creates one on a [run](https://dev.nominal.io/python/guides/runs.md).

## Find events

[`search_events()`](https://dev.nominal.io/python/ref/generated/nominal.core.NominalClient.md#nominal.core.NominalClient.search_events "nominal.core.NominalClient.search_events") combines its filters with AND:

```python
now = datetime.now(timezone.utc)
events = client.search_events(
    after=now - timedelta(days=1),  # ends after this time
    before=now,  # starts before this time
    assets=[asset],
    labels=["critical"],
)
```

`after` and `before` find events that overlap the window.
The reference lists the other filters, such as `event_type`, `created_by` and `workbook`.

Retrieve events by RID with [`get_event()`](https://dev.nominal.io/python/ref/generated/nominal.core.NominalClient.md#nominal.core.NominalClient.get_event "nominal.core.NominalClient.get_event"), which raises if the event doesn’t exist.
[`get_events()`](https://dev.nominal.io/python/ref/generated/nominal.core.NominalClient.md#nominal.core.NominalClient.get_events "nominal.core.NominalClient.get_events") takes several RIDs and leaves out any that don’t resolve.
To copy an event’s RID in the UI, click the event in a workbook and select **Copy RID**.

## Update or archive an event

[`update()`](https://dev.nominal.io/python/ref/generated/nominal.core.Event.md#nominal.core.Event.update "nominal.core.Event.update") replaces each field you pass and leaves fields passed as `None` unchanged.
Its `type` argument is required, so pass `type=None` to keep the type:

```python
event.update(labels=[*event.labels, "reviewed"], type=None)
```

[`archive()`](https://dev.nominal.io/python/ref/generated/nominal.core.Event.md#nominal.core.Event.archive "nominal.core.Event.archive") hides the event:

```python
event.archive()
```