> 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.

# Reading a Simulation's History

```python
# Imports (run once)
from typing import Iterator

from air_sdk import AirApi, SimState
from air_sdk.endpoints import Simulation
from air_sdk.types import HistoryEntry
```

```python
# Authentication (run once)
api = AirApi.with_ngc_config()
# OR api = AirApi.with_api_key(api_key="...")
# OR api = AirApi.with_device_login(email="...", org_num="...")
#    ^ use in terminal only — not supported in Jupyter notebooks
```

### Simulation History Feature

The Simulation History feature is designed to automatically log events each time a simulation (`api.endpoints.Simulation`) is created and during key operations on the simulation such as adding a ZTP script or the enabling/disabling of automatic OOB.

### Accessing Simulation History

To retrieve the history associated with a specific simulation, use the `list_history` method available on the `Simulation` object; this returns an iterator of read-only `HistoryEntry` dicts. The following are optional filtering parameters that may be passed to the `list_history` method:

* `severity`
* `actor`
* `label` — only return entries carrying a given label (e.g. `label='publishing'`)
* `search`
* `ordering`
* `limit`
* `offset`

`list_history` is also available on `Node`, `Image`, and `MarketplaceDemo` objects — each reads its own resource's history. Publishing-lifecycle actions on images and marketplace demos (publish/unpublish/approve/deny/visibility changes) are recorded with the `publishing` label, so `resource.list_history(label='publishing')` returns just those entries.

> **Note:** `Simulation` also exposes an older `get_history()` method that reads the legacy flat history endpoint (returning `History` objects with `category`/`tags`). It is deprecated in favor of `list_history()` and emits a `DeprecationWarning`.

### Immutability of History Instances

History instances are immutable and cannot be instantiated directly by clients. This ensures the integrity and consistency of the historical data. As a result, `History` instances may not be refreshed or deleted by clients.

### Creating and Listing `History`

```python
# Create a simulation with a JSON import
json_data = {
    'format': 'JSON',
    'name': 'JSON Sim',
    'content': {
        'nodes': {
            'node1': {
                'cpu': 2,
                'memory': 1024,
                'storage': 10,
                'os': 'generic/ubuntu2204',
                'cpu_arch': 'x86',
            },
        },
        'oob': False,
    },
}

sim: Simulation = api.simulations.import_from_data(**json_data)
print('waiting for simulation to finish importing...', end='')
sim.wait_for_state(SimState.INACTIVE, error_states=SimState.INVALID)

# Add a ZTP Script
ztp_script_path = '../files/ztp/basic_script.sh'
with open(ztp_script_path, 'r') as f:
    sim.create_ztp_script(content=f.read())

# Enable automatic OOB
sim.enable_auto_oob()
```

```
waiting for simulation to finish importing....
```

Now that a simulation has been created and operations have been performed on the simulation, the history of the simulation may be retrieved and viewed.

```python
history_iter: Iterator[HistoryEntry] = sim.list_history(ordering='created')
entries = list(history_iter)

for entry in entries:
    print(
        entry['actor'].ljust(12),
        f'({entry["created"].strftime("%Y-%m-%d %H:%M:%S.%f")}):',
        entry['description'],
    )
```

```
Jensen Huang (2025-04-07 18:38:09.223522): Simulation `JSON Sim` with ID `2311ab4d-f522-48e9-85c2-0f985e7207d9` created by importing a topology in `JSON` format. Topology is scheduled for validation.
NVIDIA Air   (2025-04-07 18:38:09.227707): Initiating topology validation.
NVIDIA Air   (2025-04-07 18:38:09.034142): Validation complete. Initiating creation of simulation objects.
NVIDIA Air   (2025-04-07 18:38:11.450142): Topology successfully imported.
NVIDIA Air   (2025-04-07 18:38:11.453826): Transitioning from `IMPORTING` to `INACTIVE` state.
Jensen Huang (2025-04-07 18:38:12.910011): ZTP script added.
Jensen Huang (2025-04-07 18:38:14.220142): Enabled automatic OOB
```

```python
entries[-1] if entries else None
```

```
{'object_id': '2311ab4d-f522-48e9-85c2-0f985e7207d9',
 'model': 'simulation',
 'created': datetime.datetime(2025, 4, 7, 18, 38, 14, 380638, tzinfo=datetime.timezone.utc),
 'actor': 'Jensen Huang',
 'description': 'Enabled automatic OOB',
 'severity': 'INFO',
 'labels': []}
```

### Building Filter UIs with `get_history_filters`

To discover the values you can filter a resource's history by, call `get_history_filters()`. It returns the distinct `actors`, `severities`, and `labels` present across that resource's history — the options that would populate a filter dropdown:

```python
filters = sim.get_history_filters()
# {'actors': ['Jensen Huang', 'NVIDIA Air'], 'severities': ['INFO'], 'labels': []}

# The same method is available on images and marketplace demos:
image_filters = image.get_history_filters()
```

Like `list_history`, this method is available on `Simulation`, `Image`, and `MarketplaceDemo`.