---
sidebar:
  hidden: true
title: roboto.domain.events.event
---
## Module Contents

### Event

```python
class roboto.domain.events.event.Event(
    record: roboto.domain.events.record.EventRecord,
    roboto_client: Optional[roboto.http.RobotoClient] = None,
)
```

`from roboto import Event`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L72-L1311)

Represents an event within the Roboto platform.

An event is a time-anchored annotation that relates Roboto entities (datasets, files, topics, and message paths) to specific time periods. Events enable temporal analysis, data correlation, and annotation of activities across different data sources.

Events serve as temporal markers that can:

- Annotate specific time periods in your data
- Associate multiple entities (datasets, files, topics, message paths) with time ranges
- Enable time-based data retrieval and analysis
- Support metadata and tagging for organization and search
- Provide visual markers in timeline views and analysis tools

Events can represent instantaneous moments (point in time) or time ranges. They are particularly useful for marking significant occurrences like sensor anomalies, system events, behavioral patterns, or any other time-based phenomena in your data.

Events cannot be instantiated directly through the constructor. Use the class methods [`Event.create()`](/reference/python-sdk/roboto/domain/events/event#roboto.domain.events.event.Event.create) to create new events or [`Event.from_id()`](/reference/python-sdk/roboto/domain/events/event#roboto.domain.events.event.Event.from_id) to load existing events.

**Parameters**

- **record** (`roboto.domain.events.record.EventRecord`)
- **roboto_client** (`Optional[roboto.http.RobotoClient]`)

**Properties**

- **Event.color** (`str | None`): Display color for the event, if set.

  Return type: `Optional[str]`

- **Event.created** (`datetime.datetime`): Date and time when this event was created.

- **Event.created_by** (`str`): User who created this event.

- **Event.custom_fields** (`dict[str, Any]`): Custom-field values defined on Events in this org.

  Every `Ready` [`CustomField`](/reference/python-sdk/roboto/domain/custom_fields/custom_field#roboto.domain.custom_fields.custom_field.CustomField) defined for `(org_id, Event)` appears as a key. Values that have not been set on this event surface as `None` rather than being absent. Empty when no custom fields are defined for the org.

  A [`Timestamp`](/reference/python-sdk/roboto/domain/custom_fields/record#roboto.domain.custom_fields.record.CustomFieldType.Timestamp) value is returned as an ISO 8601 string.

- **Event.description** (`str | None`): Optional human-readable description of the event.

  Return type: `Optional[str]`

- **Event.display_options** (`roboto.domain.events.operations.EventDisplayOptions | None`): Display options for the event, such as color.

  Return type: `Optional[roboto.domain.events.operations.EventDisplayOptions]`

- **Event.end_time** (`int`): End time of the event in nanoseconds since UNIX epoch.

- **Event.event_id** (`str`): Unique identifier for this event.

- **Event.metadata** (`dict[str, Any]`): Key-value metadata associated with this event.

- **Event.modified** (`datetime.datetime`): Date and time when this event was last modified.

- **Event.modified_by** (`str`): User who last modified this event.

- **Event.name** (`str`): Human-readable name of the event.

- **Event.record** (`roboto.domain.events.record.EventRecord`): Underlying event record data.

- **Event.start_time** (`int`): Start time of the event in nanoseconds since UNIX epoch.

- **Event.tags** (`list[str]`): Tags associated with this event for categorization and search.

#### Event.clear_custom_field()

```python
def clear_custom_field(name: str) -> Event
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L997-L999)

Clear a single custom-field value on this event to `None`.

**Parameters**

- **name** (`str`)

**Returns**

- `Event`

#### Event.clear_custom_fields()

```python
def clear_custom_fields(names: collections.abc.Sequence[str]) -> Event
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L1012-L1014)

Clear multiple custom-field values on this event to `None`.

**Parameters**

- **names** (`collections.abc.Sequence[str]`)

**Returns**

- `Event`

#### Event.create()

```python
@classmethod
def create(
    name: str,
    start_time: roboto.time.Time,
    end_time: Optional[roboto.time.Time] = None,
    associations: Optional[collections.abc.Collection[roboto.association.Association]] = None,
    dataset_ids: Optional[collections.abc.Collection[str]] = None,
    file_ids: Optional[collections.abc.Collection[str]] = None,
    topic_ids: Optional[collections.abc.Collection[str]] = None,
    message_path_ids: Optional[collections.abc.Collection[str]] = None,
    description: Optional[str] = None,
    metadata: Optional[dict[str, Any]] = None,
    tags: Optional[list[str]] = None,
    display_options: Optional[roboto.domain.events.operations.EventDisplayOptions] = None,
    custom_fields: Optional[dict[str, Any]] = None,
    caller_org_id: Optional[str] = None,
    roboto_client: Optional[roboto.http.RobotoClient] = None,
) -> Event
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L100-L222)

Create a new event associated with at least one dataset, file, topic, or message path.

Creates a time-anchored event that can be associated with various Roboto entities. For instantaneous events (a point in time), only `start_time` is required. Otherwise, both `start_time` and `end_time` should be provided. These fields accept nanoseconds since the UNIX epoch, or any other compatible representations supported by [`to_epoch_nanoseconds()`](/reference/python-sdk/roboto/time#roboto.time.to_epoch_nanoseconds).

Events must be associated with at least one entity. While `associations`, `file_ids`, `topic_ids`, `dataset_ids` and `message_path_ids` are all optional, at least one of them must contain a valid association for the event.

**Parameters**

- **name** (`str`): Human-readable name for the event. Required.
- **start_time** (`roboto.time.Time`): Start timestamp of the event as nanoseconds since UNIX epoch, or any value convertible by [`to_epoch_nanoseconds()`](/reference/python-sdk/roboto/time#roboto.time.to_epoch_nanoseconds).
- **end_time** (`Optional[roboto.time.Time]`): End timestamp of the event. If not provided, defaults to start_time for instantaneous events.
- **associations** (`Optional[collections.abc.Collection[roboto.association.Association]]`): Collection of [`Association`](/reference/python-sdk/roboto/association#roboto.association.Association) objects linking the event to specific entities.
- **dataset_ids** (`Optional[collections.abc.Collection[str]]`): Dataset IDs to associate the event with.
- **file_ids** (`Optional[collections.abc.Collection[str]]`): File IDs to associate the event with.
- **topic_ids** (`Optional[collections.abc.Collection[str]]`): Topic IDs to associate the event with.
- **message_path_ids** (`Optional[collections.abc.Collection[str]]`): Message path IDs to associate the event with.
- **description** (`Optional[str]`): Optional human-readable description of the event.
- **metadata** (`Optional[dict[str, Any]]`): Key-value metadata for discovery and search.
- **tags** (`Optional[list[str]]`): Tags for categorizing and searching the event.
- **display_options** (`Optional[roboto.domain.events.operations.EventDisplayOptions]`): Visual display options such as color.
- **custom_fields** (`Optional[dict[str, Any]]`): Optional initial values for Ready custom fields defined on Events in the caller's org. Keys must match Ready field names; values must satisfy each field's declared type.
- **caller_org_id** (`Optional[str]`): Organization ID of the SDK caller. If not provided, uses the caller's organization.
- **roboto_client** (`Optional[roboto.http.RobotoClient]`): HTTP client for API communication. If None, uses the default client.

**Returns**

- `Event`: Event instance with the provided attributes and associations.

**Raises**

- [`RobotoInvalidRequestException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoInvalidRequestException): Invalid parameters (e.g., start_time > end_time), or associations point to non-existent resources.
- [`RobotoUnauthorizedException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoUnauthorizedException): Caller lacks permission to access associated entities.

**Usage**

Create an event for a sensor anomaly on a specific topic:

```python
from roboto.domain.events import Event
event = Event.create(
    name="Temperature Spike",
    start_time=1722870127699468923,
    end_time=1722870127799468923,
    description="Unusual temperature readings detected",
    topic_ids=["tp_abc123"],
    tags=["anomaly", "temperature"],
    metadata={"severity": "high", "sensor_id": "temp_01"},
)
```

Create an instantaneous event on a file:

```python
event = Event.create(
    name="System Boot",
    start_time="1722870127.699468923",  # String format also supported
    file_ids=["fl_xyz789"],
    tags=["system", "boot"],
)
```

Create an event with display options:

```python
from roboto.domain.events import EventDisplayOptions
event = Event.create(
    name="Critical Alert",
    start_time=1722870127699468923,
    end_time=1722870127799468923,
    dataset_ids=["ds_abc123"],
    display_options=EventDisplayOptions(color="red"),
    metadata={"alert_type": "critical", "component": "engine"},
)
```

#### Event.dataset_ids()

```python
def dataset_ids(strict_associations: bool = False) -> list[str]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L612-L640)

Get dataset IDs associated with this event.

**Parameters**

- **strict_associations** (`bool`): If True, only return datasets with direct associations. If False (default), also return datasets inferred from file and topic associations.

**Returns**

- `list[str]`: List of unique dataset IDs associated with this event.

**Usage**

Get all associated dataset IDs:

```python
event = Event.from_id("ev_abc123")
dataset_ids = event.dataset_ids()
print(f"Associated with {len(dataset_ids)} datasets")
```

Get only directly associated datasets:

```python
strict_dataset_ids = event.dataset_ids(strict_associations=True)
print(f"Directly associated with {len(strict_dataset_ids)} datasets")
```

#### Event.delete()

```python
def delete() -> None
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L642-L666)

Delete this event permanently.

This operation cannot be undone. The event and all its associations will be permanently removed from the platform.

**Raises**

- [`RobotoUnauthorizedException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoUnauthorizedException): Caller lacks permission to delete this event.
- [`RobotoNotFoundException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoNotFoundException): Event has already been deleted or does not exist.

**Returns**

- `None`

**Usage**

Delete an event:

```python
event = Event.from_id("ev_abc123")
event.delete()
# Event is now permanently deleted
```

Conditional deletion:

```python
event = Event.from_id("ev_abc123")
if "temporary" in event.tags:
    event.delete()
    print("Temporary event deleted")
```

#### Event.delete_many()

```python
@classmethod
def delete_many(
    event_ids: collections.abc.Collection[str],
    roboto_client: Optional[roboto.http.RobotoClient] = None,
) -> None
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L462-L512)

Delete multiple events.

Authorization works just like [`delete()`](/reference/python-sdk/roboto/domain/events/event#roboto.domain.events.event.Event.delete): you can delete any event you're able to manage. If the list includes an event you're not allowed to delete, the whole request is rejected and nothing is deleted. This operation cannot be undone. Event IDs that don't exist are ignored, so the call is idempotent and safe to retry.

The bulk delete API caps each request at [`MAX_EVENTS_PER_DELETE_BATCH`](/reference/python-sdk/roboto/domain/events/operations#roboto.domain.events.operations.MAX_EVENTS_PER_DELETE_BATCH) event IDs. This method removes that limit for callers by splitting `event_ids` into chunks of that size and sending one request per chunk. Because each chunk is its own request, deleting a very large number of events is not atomic: if a request fails partway through, earlier chunks stay deleted. The operation is idempotent, so retrying with the same IDs safely finishes the job.

**Parameters**

- **event_ids** (`collections.abc.Collection[str]`): IDs of the events to delete. May exceed the per-request limit; they are batched automatically.
- **roboto_client** (`Optional[roboto.http.RobotoClient]`): HTTP client for API communication. If None, uses the default client.

**Raises**

- [`RobotoUnauthorizedException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoUnauthorizedException): Caller isn't allowed to delete one of the requested events.

**Returns**

- `None`

**Usage**

Delete several events at once:

```python
from roboto.domain.events import Event
Event.delete_many(["ev_abc123", "ev_def456", "ev_ghi789"])
```

Delete the events surfaced by a query:

```python
events = list(Event.get_by_dataset("ds_abc123"))
Event.delete_many([event.event_id for event in events])
```

#### Event.file_ids()

```python
def file_ids(strict_associations: bool = False) -> list[str]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L668-L697)

Get file IDs associated with this event.

**Parameters**

- **strict_associations** (`bool`): If True, only return files with direct associations. If False (default), also return files inferred from topic and message path associations.

**Returns**

- `list[str]`: List of unique file IDs associated with this event.

**Usage**

Get all associated file IDs:

```python
event = Event.from_id("ev_abc123")
file_ids = event.file_ids()
print(f"Associated with {len(file_ids)} files")
```

Get only directly associated files:

```python
strict_file_ids = event.file_ids(strict_associations=True)
for file_id in strict_file_ids:
    print(f"Directly associated file: {file_id}")
```

#### Event.from_id()

```python
@classmethod
def from_id(
    event_id: str,
    roboto_client: Optional[roboto.http.RobotoClient] = None,
) -> Event
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L430-L459)

Load an existing event by its ID.

**Parameters**

- **event_id** (`str`): Unique identifier of the event to retrieve.
- **roboto_client** (`Optional[roboto.http.RobotoClient]`): HTTP client for API communication. If None, uses the default client.

**Returns**

- `Event`: Event instance for the specified ID.

**Raises**

- [`RobotoNotFoundException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoNotFoundException): Event with the specified ID does not exist.
- [`RobotoUnauthorizedException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoUnauthorizedException): Caller lacks permission to access the event.

**Usage**

Load an event by ID:

```python
event = Event.from_id("ev_abc123")
print(f"Event: {event.name}")
print(f"Created: {event.created}")
```

Load and update an event:

```python
event = Event.from_id("ev_abc123")
updated_event = event.set_description("Updated description")
print(f"New description: {updated_event.description}")
```

#### Event.get_by_associations()

```python
@classmethod
def get_by_associations(
    associations: collections.abc.Collection[roboto.association.Association],
    roboto_client: Optional[roboto.http.RobotoClient] = None,
) -> collections.abc.Generator[Event, None, None]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L379-L427)

Retrieve all events associated with the provided associations.

Returns events that match any of the provided associations. Events that you don't have access to will be filtered out of the response rather than raising an exception.

**Parameters**

- **associations** (`collections.abc.Collection[roboto.association.Association]`): Collection of [`Association`](/reference/python-sdk/roboto/association#roboto.association.Association) objects to query events for.
- **roboto_client** (`Optional[roboto.http.RobotoClient]`): HTTP client for API communication. If None, uses the default client.

**Yields**

- Event instances associated with any of the specified associations.

**Returns**

- `collections.abc.Generator[Event, None, None]`

**Usage**

Query events for multiple associations:

```python
from roboto import Association
associations = [Association.topic("tp_abc123"), Association.file("fl_xyz789")]
events = list(Event.get_by_associations(associations))
for event in events:
    print(f"Event: {event.name}")
```

Query events for a specific dataset and file combination:

```python
associations = [Association.dataset("ds_abc123"), Association.file("fl_xyz789")]
events = list(Event.get_by_associations(associations))
```

#### Event.get_by_dataset()

```python
@classmethod
def get_by_dataset(
    dataset_id: str,
    roboto_client: Optional[roboto.http.RobotoClient] = None,
    strict_associations: bool = False,
) -> collections.abc.Generator[Event, None, None]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L225-L287)

Retrieve all events associated with a specific dataset.

Returns events that are associated with the given dataset. By default, this includes events associated with the dataset itself, as well as events associated with any files or topics within that dataset. Use `strict_associations=True` to only return events with direct dataset associations.

**Parameters**

- **dataset_id** (`str`): ID of the dataset to query events for.
- **roboto_client** (`Optional[roboto.http.RobotoClient]`): HTTP client for API communication. If None, uses the default client.
- **strict_associations** (`bool`): If True, only return events with direct dataset associations. If False (default), also return events associated with files or topics within the dataset.

**Yields**

- Event instances associated with the specified dataset.

**Returns**

- `collections.abc.Generator[Event, None, None]`

**Usage**

Get all events for a dataset (including file and topic events):

```python
events = list(Event.get_by_dataset("ds_abc123"))
for event in events:
    print(f"Event: {event.name} at {event.start_time}")
```

Get only events directly associated with the dataset:

```python
strict_events = list(Event.get_by_dataset("ds_abc123", strict_associations=True))
print(f"Found {len(strict_events)} dataset-level events")
```

Process events in batches:

```python
for event in Event.get_by_dataset("ds_abc123"):
    if "anomaly" in event.tags:
        print(f"Anomaly event: {event.name}")
```

#### Event.get_by_file()

```python
@classmethod
def get_by_file(
    file_id: str,
    roboto_client: Optional[roboto.http.RobotoClient] = None,
) -> collections.abc.Generator[Event, None, None]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L290-L317)

Retrieve all events with a direct association to a specific file.

**Parameters**

- **file_id** (`str`): ID of the file to query events for.
- **roboto_client** (`Optional[roboto.http.RobotoClient]`): HTTP client for API communication. If None, uses the default client.

**Yields**

- Event instances directly associated with the specified file.

**Returns**

- `collections.abc.Generator[Event, None, None]`

**Usage**

Get all events for a specific file:

```python
events = list(Event.get_by_file("fl_xyz789"))
for event in events:
    print(f"File event: {event.name}")
```

Check if a file has any events:

```python
file_events = list(Event.get_by_file("fl_xyz789"))
if file_events:
    print(f"File has {len(file_events)} events")
else:
    print("No events found for this file")
```

#### Event.get_by_message_path()

```python
@classmethod
def get_by_message_path(
    message_path_id: str,
    roboto_client: Optional[roboto.http.RobotoClient] = None,
) -> collections.abc.Generator[Event, None, None]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L320-L346)

Retrieve all events with a direct association to a specific message path.

**Parameters**

- **message_path_id** (`str`): ID of the message path to query events for.
- **roboto_client** (`Optional[roboto.http.RobotoClient]`): HTTP client for API communication. If None, uses the default client.

**Yields**

- Event instances directly associated with the specified message path.

**Returns**

- `collections.abc.Generator[Event, None, None]`

**Usage**

Get all events for a specific message path:

```python
events = list(Event.get_by_message_path("mp_abc123"))
for event in events:
    print(f"Message path event: {event.name}")
```

Find events within a time range for a message path:

```python
events = Event.get_by_message_path("mp_abc123")
filtered_events = [event for event in events if event.start_time >= 1722870127699468923]
```

#### Event.get_by_topic()

```python
@classmethod
def get_by_topic(
    topic_id: str,
    roboto_client: Optional[roboto.http.RobotoClient] = None,
) -> collections.abc.Generator[Event, None, None]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L349-L376)

Retrieve all events with a direct association to a specific topic.

**Parameters**

- **topic_id** (`str`): ID of the topic to query events for.
- **roboto_client** (`Optional[roboto.http.RobotoClient]`): HTTP client for API communication. If None, uses the default client.

**Yields**

- Event instances directly associated with the specified topic.

**Returns**

- `collections.abc.Generator[Event, None, None]`

**Usage**

Get all events for a specific topic:

```python
events = list(Event.get_by_topic("tp_abc123"))
for event in events:
    print(f"Topic event: {event.name}")
```

Analyze event patterns for a topic:

```python
events = list(Event.get_by_topic("tp_abc123"))
anomaly_events = [e for e in events if "anomaly" in e.tags]
print(f"Found {len(anomaly_events)} anomaly events")
```

#### Event.get_data()

```python
def get_data(
    message_paths_include: Optional[collections.abc.Iterable[str]] = None,
    message_paths_exclude: Optional[collections.abc.Iterable[str]] = None,
    topic_name: Optional[str] = None,
    topic_data_service: Optional[roboto.domain.topics.TopicDataService] = None,
    cache_dir: Union[str, pathlib.Path, None] = None,
    strict_associations: bool = False,
) -> collections.abc.Generator[tuple[roboto.domain.topics.Timestamp, dict[str, Any]], None, None]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L699-L786)

Iteratively yield records of the underlying topic data this event annotates.

**An event can be associated with data at multiple resolutions:**

- as an event on its containing dataset, file, and/or topic,
- but also directly with the message path ("signal data")

A single event can also span signals that share a timeline, so it may annotate multiple topics in a file, or even multiple files in a dataset.

For now, getting the underlying signal data associated with an event only works for events that can be sourced to a single topic (extracted from one file, uploaded to one dataset). This means that the event must have been made on either a single file, a single topic, or one or many message paths within that topic.

If the event was made on a file, topic_name must be provided, and either or both of message_paths_include or message_paths_exclude may be provided, but are optional.

If the event was made on a topic, either or both of message_paths_include or message_paths_exclude may be provided, but are optional. topic_name, if provided in this instance, is ignored.

If the event was made on one or many message paths, each of those message paths must be found in the same topic. topic_name, message_paths_include, and message_paths_exclude, if provided in this instance, are ignored.

If the event is associated with data at multiple resolutions (e.g., two message paths, one topic, one file), this method will consider the lowest resolution associations first (message path), then topic, then file.

If `message_paths_include` or `message_paths_exclude` are defined, they should be dot notation paths that match attributes of individual data records. If a partial path is provided, it is treated as a wildcard, matching all subpaths.

For example, given topic data with the following interface:

```
{
    "velocity": {
        "x": <uint32>,
        "y": <uint32>,
        "z": <uint32>
    }
}
```

Calling `get_data` on an Event associated with that topic like:

> ```python
> event.get_data(message_paths_include=["velocity.x", "velocity.y"])
> ```

is expected to give the same output as:

> ```python
> event.get_data(message_paths_include=["velocity"], message_paths_exclude=["velocity.z"])
> ```

> **Tip**
>
> For many events, parallelize with a thread pool:
>
> ```python
> from concurrent.futures import ThreadPoolExecutor
> from itertools import chain
> with ThreadPoolExecutor(max_workers=16) as ex:  # tune for your workload
>     results = list(ex.map(lambda e: list(e.get_data()), events))
> merged = list(chain.from_iterable(results))
> ```

**Parameters**

- **message_paths_include** (`Optional[collections.abc.Iterable[str]]`)
- **message_paths_exclude** (`Optional[collections.abc.Iterable[str]]`)
- **topic_name** (`Optional[str]`)
- **topic_data_service** (`Optional[roboto.domain.topics.TopicDataService]`)
- **cache_dir** (`Union[str, pathlib.Path, None]`)
- **strict_associations** (`bool`)

**Returns**

- `collections.abc.Generator[tuple[roboto.domain.topics.Timestamp, dict[str, Any]], None, None]`

#### Event.get_data_as_df()

```python
def get_data_as_df(
    message_paths_include: Optional[collections.abc.Iterable[str]] = None,
    message_paths_exclude: Optional[collections.abc.Iterable[str]] = None,
    topic_name: Optional[str] = None,
    topic_data_service: Optional[roboto.domain.topics.TopicDataService] = None,
    cache_dir: Union[str, pathlib.Path, None] = None,
    strict_associations: bool = False,
) -> pandas.DataFrame
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L788-L860)

Return the underlying topic data this event annotates as a pandas DataFrame.

Collects all data from [`get_data()`](/reference/python-sdk/roboto/domain/events/event#roboto.domain.events.event.Event.get_data) and returns it as a pandas DataFrame with the log time as the index. Requires installing this package using the `roboto[analytics]` extra.

**Parameters**

- **message_paths_include** (`Optional[collections.abc.Iterable[str]]`): Dot notation paths to include in the data.
- **message_paths_exclude** (`Optional[collections.abc.Iterable[str]]`): Dot notation paths to exclude from the data.
- **topic_name** (`Optional[str]`): Required when event is associated with a file.
- **topic_data_service** (`Optional[roboto.domain.topics.TopicDataService]`): Service for accessing topic data.
- **cache_dir** (`Union[str, pathlib.Path, None]`): Directory for caching downloaded data.
- **strict_associations** (`bool`)

**Returns**

- `pandas.DataFrame`: DataFrame containing the event's underlying topic data, indexed by log time.

**Raises**

- `ImportError`: If pandas is not installed (install with `roboto[analytics]`).
- [`RobotoInvalidRequestException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoInvalidRequestException): Invalid parameters or event associations.

**Usage**

Get event data as a DataFrame:

```python
event = Event.from_id("ev_abc123")
df = event.get_data_as_df()
print(f"Data shape: {df.shape}")
print(df.head())
```

Get specific message paths as DataFrame:

```python
df = event.get_data_as_df(message_paths_include=["velocity.x", "velocity.y"])
print(df.columns.tolist())
```

Analyze event data:

```python
df = event.get_data_as_df()
print(f"Event duration: {df.index.max() - df.index.min()} ns")
print(f"Data points: {len(df)}")
```

> **Tip**
>
> For many events, parallelize with a thread pool:
>
> ```python
> import pandas as pd
> from concurrent.futures import ThreadPoolExecutor
> with ThreadPoolExecutor(max_workers=16) as ex:  # tune for your workload
>     dfs = list(ex.map(lambda e: e.get_data_as_df(), events))
> combined = pd.concat(dfs).sort_index()
> ```

#### Event.message_path_ids()

```python
def message_path_ids() -> list[str]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L862-L881)

Get message path IDs directly associated with this event.

**Returns**

- `list[str]`: List of unique message path IDs directly associated with this event.

**Usage**

Get message path IDs:

```python
event = Event.from_id("ev_abc123")
msgpath_ids = event.message_path_ids()
print(f"Associated with {len(msgpath_ids)} message paths")
```

#### Event.put_metadata()

```python
def put_metadata(metadata: dict[str, Any]) -> Event
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L883-L900)

Add or update metadata fields for this event.

**Parameters**

- **metadata** (`dict[str, Any]`): Dictionary of key-value pairs to add or update.

**Returns**

- `Event`: Updated Event instance.

**Usage**

Add metadata to an event:

```python
event = Event.from_id("ev_abc123")
updated_event = event.put_metadata({"severity": "high", "component": "engine", "alert_id": "alert_001"})
print(updated_event.metadata["severity"])
# 'high'
```

#### Event.put_tags()

```python
def put_tags(tags: list[str]) -> Event
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L902-L919)

Replace all tags for this event.

**Parameters**

- **tags** (`list[str]`): List of tags to set for this event.

**Returns**

- `Event`: Updated Event instance.

**Usage**

Set tags for an event:

```python
event = Event.from_id("ev_abc123")
updated_event = event.put_tags(["anomaly", "critical", "engine"])
print(updated_event.tags)
# ['anomaly', 'critical', 'engine']
```

#### Event.refresh()

```python
def refresh() -> Event
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L921-L939)

Refresh this event's data from the server.

Fetches the latest version of this event from the server, updating all properties to reflect any changes made by other processes.

**Returns**

- `Event`: This Event instance with refreshed data.

**Usage**

Refresh an event to get latest changes:

```python
event = Event.from_id("ev_abc123")
# Event may have been updated by another process
refreshed_event = event.refresh()
print(f"Current description: {refreshed_event.description}")
```

#### Event.remove_metadata()

```python
def remove_metadata(metadata: roboto.updates.StrSequence) -> Event
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L941-L961)

Remove metadata fields from this event.

**Parameters**

- **metadata** (`roboto.updates.StrSequence`): Sequence of metadata field names to remove. Supports dot notation for nested fields.

**Returns**

- `Event`: Updated Event instance.

**Usage**

Remove specific metadata fields:

```python
event = Event.from_id("ev_abc123")
updated_event = event.remove_metadata(["severity", "temp_data.max"])
# Fields 'severity' and nested 'temp_data.max' are now removed
```

#### Event.remove_tags()

```python
def remove_tags(tags: roboto.updates.StrSequence) -> Event
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L963-L982)

Remove specific tags from this event.

**Parameters**

- **tags** (`roboto.updates.StrSequence`): Sequence of tag names to remove from this event.

**Returns**

- `Event`: Updated Event instance.

**Usage**

Remove specific tags:

```python
event = Event.from_id("ev_abc123")
updated_event = event.remove_tags(["temporary", "draft"])
# Tags 'temporary' and 'draft' are now removed
```

#### Event.set_color()

```python
def set_color(color: Optional[str]) -> Event
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L1016-L1040)

Set the display color for this event.

**Parameters**

- **color** (`Optional[str]`): CSS-compatible color value (e.g., "red", "#ff0000", "rgb(255,0,0)"). Use None to clear the color and use automatic coloring.

**Returns**

- `Event`: Updated Event instance.

**Usage**

Set event color to red:

```python
event = Event.from_id("ev_abc123")
updated_event = event.set_color("red")
print(updated_event.color)
# 'red'
```

Clear event color:

```python
updated_event = event.set_color(None)
print(updated_event.color)
# None
```

#### Event.set_custom_field()

```python
def set_custom_field(name: str, value: Any) -> Event
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L985-L994)

Set a single custom-field value on this event.

`name` must be the name of a [`Ready`](/reference/python-sdk/roboto/domain/custom_fields/record#roboto.domain.custom_fields.record.CustomFieldStatus.Ready) custom field for this event's org and the [`Event`](/reference/python-sdk/roboto/domain/custom_fields/record#roboto.domain.custom_fields.record.TargetEntityType.Event) entity type; `value` must satisfy the field's declared type.

**Parameters**

- **name** (`str`)
- **value** (`Any`)

**Returns**

- `Event`

#### Event.set_custom_fields()

```python
def set_custom_fields(fields: dict[str, Any]) -> Event
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L1002-L1009)

Set or overwrite multiple custom-field values on this event.

Each key must name a Ready custom field for this event's org and the [`Event`](/reference/python-sdk/roboto/domain/custom_fields/record#roboto.domain.custom_fields.record.TargetEntityType.Event) entity type; each value must satisfy the field's declared type.

**Parameters**

- **fields** (`dict[str, Any]`)

**Returns**

- `Event`

#### Event.set_description()

```python
def set_description(description: Optional[str]) -> Event
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L1042-L1065)

Set the description for this event.

**Parameters**

- **description** (`Optional[str]`): New description for the event. Use None to clear the description.

**Returns**

- `Event`: Updated Event instance.

**Usage**

Set event description:

```python
event = Event.from_id("ev_abc123")
updated_event = event.set_description("Updated event description")
print(updated_event.description)
# 'Updated event description'
```

Clear event description:

```python
updated_event = event.set_description(None)
print(updated_event.description)
# None
```

#### Event.set_name()

```python
def set_name(name: str) -> Event
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L1067-L1084)

Set the name for this event.

**Parameters**

- **name** (`str`): New name for the event.

**Returns**

- `Event`: Updated Event instance.

**Usage**

Update event name:

```python
event = Event.from_id("ev_abc123")
updated_event = event.set_name("Critical System Alert")
print(updated_event.name)
# 'Critical System Alert'
```

#### Event.to_dict()

```python
def to_dict() -> dict[str, Any]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L1086-L1100)

Convert this event to a dictionary representation.

**Returns**

- `dict[str, Any]`: Dictionary containing all event data in JSON-serializable format.

**Usage**

Convert event to dictionary:

```python
event = Event.from_id("ev_abc123")
event_dict = event.to_dict()
print(event_dict["name"])
print(event_dict["start_time"])
```

#### Event.topic_ids()

```python
def topic_ids(strict_associations: bool = False) -> list[str]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L1102-L1131)

Get topic IDs associated with this event.

**Parameters**

- **strict_associations** (`bool`): If True, only return topics with direct associations. If False (default), also return topics inferred from message path associations.

**Returns**

- `list[str]`: List of unique topic IDs associated with this event.

**Usage**

Get all associated topic IDs:

```python
event = Event.from_id("ev_abc123")
topic_ids = event.topic_ids()
print(f"Associated with {len(topic_ids)} topics")
```

Get only directly associated topics:

```python
strict_topic_ids = event.topic_ids(strict_associations=True)
for topic_id in strict_topic_ids:
    print(f"Directly associated topic: {topic_id}")
```

#### Event.update()

```python
def update(
    name: Union[str, roboto.sentinels.NotSetType] = NotSet,
    start_time: Union[roboto.time.Time, roboto.sentinels.NotSetType] = NotSet,
    end_time: Union[roboto.time.Time, roboto.sentinels.NotSetType] = NotSet,
    description: Union[str, None, roboto.sentinels.NotSetType] = NotSet,
    metadata_changeset: Union[roboto.updates.MetadataChangeset, roboto.sentinels.NotSetType] = NotSet,
    display_options_changeset: Union[roboto.domain.events.operations.EventDisplayOptionsChangeset, roboto.sentinels.NotSetType] = NotSet,
    custom_fields_changeset: Optional[roboto.updates.CustomFieldChangeset] = None,
) -> Event
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L1133-L1219)

Update this event's attributes.

Updates various properties of the event including name, time range, description, metadata, and display options. Only specified parameters are updated; others remain unchanged.

When provided, `start_time` and `end_time` should be integers representing nanoseconds since the UNIX epoch, or convertible to such integers by [`to_epoch_nanoseconds()`](/reference/python-sdk/roboto/time#roboto.time.to_epoch_nanoseconds).

**Parameters**

- **name** (`Union[str, roboto.sentinels.NotSetType]`): New human-readable name for the event.
- **start_time** (`Union[roboto.time.Time, roboto.sentinels.NotSetType]`): New start timestamp for the event.
- **end_time** (`Union[roboto.time.Time, roboto.sentinels.NotSetType]`): New end timestamp for the event.
- **description** (`Union[str, None, roboto.sentinels.NotSetType]`): New description for the event. Set to None to clear existing description.
- **metadata_changeset** (`Union[roboto.updates.MetadataChangeset, roboto.sentinels.NotSetType]`): Changes to apply to the event's metadata and tags.
- **display_options_changeset** (`Union[roboto.domain.events.operations.EventDisplayOptionsChangeset, roboto.sentinels.NotSetType]`): Changes to apply to the event's display options.
- **custom_fields_changeset** (`Optional[roboto.updates.CustomFieldChangeset]`): Changes to apply to Ready custom-field values on this event. Field names not referenced by the changeset are left unchanged.

**Returns**

- `Event`: This Event instance with attributes updated accordingly.

**Raises**

- `ValueError`: If start_time or end_time are negative.
- [`RobotoIllegalArgumentException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoIllegalArgumentException): If start_time > end_time.
- [`RobotoUnauthorizedException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoUnauthorizedException): Caller lacks permission to edit this event.

**Usage**

Update event name and description:

```python
event = Event.from_id("ev_abc123")
updated_event = event.update(
    name="Critical System Alert", description="Updated description with more details"
)
```

Update event time range:

```python
updated_event = event.update(start_time=1722870127699468923, end_time=1722870127799468923)
```

Update metadata and display options:

```python
from roboto.updates import MetadataChangeset
from roboto.domain.events import EventDisplayOptionsChangeset
updated_event = event.update(
    metadata_changeset=MetadataChangeset(
        put_fields={"severity": "high"}, put_tags=["critical", "urgent"]
    ),
    display_options_changeset=EventDisplayOptionsChangeset(color="red"),
)
```

### GetDataArgs

```python
class roboto.domain.events.event.GetDataArgs
```

`from roboto.domain.events.event import GetDataArgs`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L59-L69)

Internal interface used to collect arguments passed to `get_data` and `get_data_as_df`.

**Attributes**

- **GetDataArgs.cache_dir** (`str | pathlib.Path | None`) = `None`
- **GetDataArgs.end_time** (`roboto.time.Time | None`) = `None`
- **GetDataArgs.message_paths_exclude** (`collections.abc.Iterable[str] | None`) = `None`
- **GetDataArgs.message_paths_include** (`collections.abc.Iterable[str] | None`) = `None`
- **GetDataArgs.start_time** (`roboto.time.Time | None`) = `None`
- **GetDataArgs.topic** (`roboto.domain.topics.Topic`)

### logger

```python
roboto.domain.events.event.logger
```

`from roboto.domain.events.event import logger`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/events/event.py#L55-L55)