> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/dsx-air/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/dsx-air/_mcp/server.

# air_sdk.endpoints.history

## Classes

| Name                                                               | Description                                                                  |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| [`History`](#air_sdkendpointshistoryhistory)                       | A history entry from the legacy flat `histories` endpoint.                   |
| [`HistoryModelMixin`](#air_sdkendpointshistoryhistorymodelmixin)   | Nested history reads for a resource (`history` + `history-filters`).         |
| [`HistoryEndpointAPI`](#air_sdkendpointshistoryhistoryendpointapi) | API for querying simulation and node history entries (legacy flat endpoint). |

## Module Contents

```python
class air_sdk.endpoints.history.History
```

**Bases**: `air_sdk.air_model.AirModel`

A history entry from the legacy flat `histories` endpoint.

Returned by `api.histories.list()` and the deprecated `Simulation.get_history()`.
Entries are immutable and read-only. For per-resource history, prefer the
nested `list_history()` (see `HistoryModelMixin`), which yields `HistoryEntry`.

> **Note**
>
> History entries cannot be created, updated, or deleted via the SDK.
> They are automatically generated by the Air API.

```python
object_id: str
```

ID of the entity this history entry is about (e.g., a simulation ID)

```python
model: str
```

Type of entity being tracked (e.g., 'simulation')

```python
created: datetime.datetime
```

Timestamp when the history entry was created

```python
actor: str
```

Email or identifier of the user who performed the action

```python
description: str
```

Human-readable description of what happened

```python
category: str
```

Category of the event. Values: 'INFO', 'ERROR'

```python
get_model_api() -> type[HistoryEndpointAPI]
```

Returns the respective `AirModelAPI` type for this model

```python
refresh() -> None
```

Refresh the history entry.

> **Note**
>
> History entries are read-only and created automatically by the Air API.
> They cannot be modified or refreshed.

**Raises:**

* `NotImplementedError` – History entries are immutable and cannot be refreshed

```python
class air_sdk.endpoints.history.HistoryModelMixin
```

Nested history reads for a resource (`history` + `history-filters`).

Provides the `list_history()` and `get_history_filters()` convenience methods
on resources that support per-resource history (`Simulation`, `Node`, `Image`,
`MarketplaceDemo`). These read the resource's own nested history endpoints
rather than the legacy flat `histories` endpoint.

```python
list_history(
    *,
    severity: str = ...,
    actor: str = ...,
    label: str = ...,
    search: str = ...,
    ordering: Literal[list_history.actor, list_history.severity, created, -actor, -severity, -created] = ...,
    limit: int = ...,
    offset: int = ...
) -> Iterator[HistoryEntry]
```

List the history entries for this resource.

Reads the resource's nested `history` endpoint and yields read-only
`HistoryEntry` dicts (newest-first by default).

**Parameters:**

* `severity` – Filter by event severity. Values: 'INFO', 'ERROR'
* `actor` – Filter by the actor who performed the action (case-insensitive)
* `label` – Only return entries carrying this label (e.g., 'publishing')
* `search` – Search for a substring across actor, description, severity, and labels
* `ordering` – Order by field. Prefix with '-' for descending order (e.g., '-created')
* `limit` – Maximum number of results to return per page
* `offset` – Number of results to skip (for pagination)

**Returns:**

Iterator of HistoryEntry dicts for this resource

**Example:**

```python
>>> for entry in simulation.list_history(ordering='-created'):
...     print(f'{entry["created"]}: {entry["description"]}')

>>> # Only publishing-lifecycle entries for an image:
>>> for entry in image.list_history(label='publishing'):
...     print(entry['description'])
```

```python
get_history_filters() -> HistoryFilters
```

Get the distinct history filter values for this resource.

Returns the distinct actors, severities, and labels present across all of
this resource's history entries - the values that populate a filter UI.
The options are the same for every caller allowed to read the history.

**Returns:**

A HistoryFilters mapping with 'actors', 'severities', and 'labels' lists.

**Example:**

```python
>>> filters = image.get_history_filters()
>>> print(filters['actors'])
>>> print(filters['labels'])
```

```python
class air_sdk.endpoints.history.HistoryEndpointAPI
```

**Bases**: `air_sdk.endpoints.mixins.ListApiMixin[air_sdk.endpoints.history.History]`, `air_sdk.air_model.BaseEndpointAPI[air_sdk.endpoints.history.History]`

API for querying simulation and node history entries (legacy flat endpoint).

History entries are read-only records of actions and events for Air resources.

> **Note**
>
> This flat endpoint serves **simulation** and **node** history. For image
> and marketplace-demo history - and as the preferred path for simulations -
> use the nested `list_history()` / `get_history_filters()` methods on the
> resource (see `HistoryModelMixin`).
>
> This endpoint only supports list() operations. History entries cannot be
> created, updated, or deleted via the API.

```python
API_PATH: str
```

```python
model: type[History]
```

```python
list(
    *,
    model: Literal[simulation, node] = ...,
    object_id: str | None = ...,
    actor: str | None = ...,
    category: str | None = ...,
    search: str | None = ...,
    ordering: str | None = ...,
    limit: int | None = ...,
    offset: int | None = ...
) -> Iterator[History]
```

List simulation and node history entries, with optional filtering and paging.

**Parameters:**

* `model` – Entity type to get history for. Accepts 'simulation' or 'node' on this legacy endpoint; image and marketplace-demo history are served by the nested resource endpoints.
* `object_id` – Filter by the ID of the entity being tracked (e.g., a specific simulation's ID)
* `actor` – Filter by actor email or identifier
* `category` – Filter by event category. Values: 'INFO', 'ERROR'
* `search` – Search for substrings in actor or description fields
* `ordering` – Order by field (prefix with '-' for descending). Available fields: actor, category, created, model, object\_id
* `limit` – Maximum number of results to return per page
* `offset` – Number of results to skip (for pagination)

**Yields:**

History instances

**Example:**

```python
>>> # List all simulation history
>>> for entry in api.histories.list(model='simulation'):
...     print(entry.description)
>>>
>>> # Get history for a specific simulation
>>> for entry in api.histories.list(
...     model='simulation',
...     object_id='3dadd54d-583c-432e-9383-a2b0b1d7f551'
... ):
...     print(f'{entry.created}: {entry.description}')
>>>
>>> # Filter by category
>>> errors = list(api.histories.list(model='simulation', category='ERROR'))
>>> print(f'Found {len(errors)} errors')
>>>
>>> # Order by creation time (newest first)
>>> for entry in api.histories.list(
...     model='simulation',
...     ordering='-created',
...     limit=5
... ):
...     print(f'{entry.created}: {entry.description}')
```