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

Stub file for simulations endpoint type hints.

## Classes

| Name                                                                         | Description                                         |
| ---------------------------------------------------------------------------- | --------------------------------------------------- |
| [`Simulation`](#air_sdkendpointssimulationssimulation)                       | Simulation model representing a network simulation. |
| [`SimulationEndpointAPI`](#air_sdkendpointssimulationssimulationendpointapi) | API client for simulation endpoints.                |

## Module Contents

```python
class air_sdk.endpoints.simulations.Simulation
```

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

Simulation model representing a network simulation.

The string representation shows: id, name, state, creator

```python
id: str
```

Unique identifier for the simulation

```python
name: str
```

Human-readable name of the simulation

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

Timestamp when the simulation was created

```python
modified: datetime.datetime
```

Timestamp when the simulation was last modified

```python
state: Literal[CLONING, CREATING, IMPORTING, INVALID, INACTIVE, REQUESTING, PROVISIONING, PREPARE_BOOT, BOOTING, ACTIVE, PREPARE_SHUTDOWN, SHUTTING_DOWN, SAVING, PREPARE_REBUILD, REBUILDING, DELETING, PREPARE_PURGE, PURGING, DEMO, TRAINING]
```

Current state of the simulation (see Literal values for all states)

```python
creator: str
```

Email of the user who created the simulation

```python
auto_oob_enabled: bool | None
```

Whether automatic out-of-band management is enabled

```python
disable_auto_oob_dhcp: bool | None
```

Whether DHCP should be disabled on the OOB server

```python
auto_netq_enabled: bool | None
```

Whether automatic NetQ is enabled

```python
sleep_at: datetime.datetime | None
```

When the simulation should be automatically put to sleep (stored)

```python
expires_at: datetime.datetime | None
```

When the simulation should be automatically deleted

```python
documentation: str | None
```

Documentation markdown or URL to documentation markdown

```python
complete_checkpoint_count: int
```

Number of complete checkpoints in the simulation

```python
metadata: str | None
```

Custom metadata as a JSON string

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

```python
model_api: SimulationEndpointAPI
```

```python
update(
    *,
    name: str | dataclasses._MISSING_TYPE = ...,
    sleep_at: datetime.datetime | None | dataclasses._MISSING_TYPE = ...,
    expires_at: datetime.datetime | None | dataclasses._MISSING_TYPE = ...,
    documentation: str | None | dataclasses._MISSING_TYPE = ...,
    metadata: str | None | dataclasses._MISSING_TYPE = ...
) -> None
```

Update the simulation's properties.

Note: For OOB, DHCP and NetQ configuration, use dedicated methods like
enable\_auto\_oob(), disable\_auto\_oob(),
enable\_auto\_netq(), disable\_auto\_netq(), etc.

**Parameters:**

* `name` – New name for the simulation
* `sleep_at` – When the simulation should be automatically put to sleep
* `expires_at` – When the simulation should be automatically deleted
* `documentation` – Documentation markdown or URL to documentation markdown
* `metadata` – Custom metadata as a JSON string

**Example:**

```python
>>> simulation.update(name='New Name', documentation='https://docs.example.com')
>>> simulation.update(metadata='{"env": "production", "version": "1.0"}')
```

```python
enable_auto_oob(disable_auto_oob_dhcp: bool = ...) -> None
```

Enable automatic Out-of-band management for this simulation.

**Parameters:**

* `disable_auto_oob_dhcp` – If True, disable DHCP on the OOB management network

**Example:**

```python
# Enable OOB  with DHCP:
>>> simulation.enable_auto_oob()

# Enable OOB without DHCP:
>>> simulation.enable_auto_oob(disable_auto_oob_dhcp=True)
```

```python
disable_auto_oob() -> None
```

Disable automatic Out-of-band management for this simulation.

**Example:**

```python
>>> simulation.disable_auto_oob()
```

```python
enable_auto_netq() -> None
```

Enable automatic NetQ for this simulation.

**Example:**

```python
>>> simulation.enable_auto_netq()
```

```python
disable_auto_netq() -> None
```

Disable automatic NetQ for this simulation.

**Example:**

```python
>>> simulation.disable_auto_netq()
```

```python
start(
    *,
    checkpoint: str | None = ...
) -> None
```

Start the simulation.

**Parameters:**

* `checkpoint` – Optional checkpoint ID to start from. If not specified, the API will use its default behavior (typically uses the most recent checkpoint if available). If explicitly set to None, starts from clean state (rebuild). If a string, starts from the specified checkpoint.

**Example:**

```python
# Normal start (API determines behavior):
>>> simulation.start()

# Start from specific checkpoint:
>>> simulation.start(checkpoint='checkpoint-id')

# Rebuild (start from clean state, no checkpoint):
>>> simulation.start(checkpoint=None)
```

```python
shutdown(
    *,
    create_checkpoint: bool = ...
) -> None
```

Shut down the simulation.

**Parameters:**

* `create_checkpoint` – Whether to create a checkpoint before shutting down. If not specified, the API will use its default behavior.

**Example:**

```python
# Normal shutdown (API determines behavior):
>>> simulation.shutdown()

# Explicitly create checkpoint before shutdown:
>>> simulation.shutdown(create_checkpoint=True)

# Explicitly don't create checkpoint:
>>> simulation.shutdown(create_checkpoint=False)
```

```python
rebuild(
    *,
    checkpoint: str | None = ...
) -> None
```

Rebuild the simulation from a given checkpoint.

Tears down the simulation and starts it from the given checkpoint.
If no checkpoint is provided, the simulation will be rebuilt from the clean state.

**Parameters:**

* `checkpoint` – Optional checkpoint ID to rebuild from. If not specified, the API will use its default behavior (the current checkpoint the simulation is running off of). If explicitly set to None, starts from clean state (rebuild). If a string, starts from the specified checkpoint.

**Example:**

```python
# Rebuild simulation from specific checkpoint:
>>> simulation.rebuild(checkpoint='checkpoint-id')
```

```python
wait_for_state(
    target_states: str | list[str],
    timeout: datetime.timedelta | None = None,
    poll_interval: datetime.timedelta | None = None,
    error_states: str | list[str] | None = None
) -> None
```

Wait for simulation to reach one of the target states.

**Parameters:**

* `target_states` – Single state or list of states to wait for
* `timeout` – Maximum time to wait (default: 120 seconds)
* `poll_interval` – Time between status checks (default: 2 seconds)
* `error_states` – Single state or list of states that should raise an error

**Raises:**

* `ValueError` – If the simulation enters one of the error states
* `TimeoutError` – If timeout is reached before target state

**Example:**

```python
>>> simulation.wait_for_state('ACTIVE', error_states=['INVALID'])

>>> # Wait for multiple possible states
>>> simulation.wait_for_state(['INACTIVE', 'ACTIVE'])

>>> # Custom timeout
>>> simulation.wait_for_state(
...     'ACTIVE',
...     timeout=timedelta(minutes=5),
...     error_states=['INVALID', 'DELETING']
... )
```

```python
set_sleep_time(sleep_at: datetime.datetime | None) -> None
```

Set when the simulation should be automatically put to sleep (stored).

Accepts any timezone-aware datetime, which will be automatically
converted to UTC. Naive datetimes (without timezone) will trigger
a warning and assume local timezone.

**Parameters:**

* `sleep_at` – Timezone-aware datetime when simulation should sleep, or None to clear. Naive datetimes will assume local timezone and emit a warning.

**Example:**

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

# Timezone-aware datetime (recommended):
>>> sleep_time = datetime.now(timezone.utc) + timedelta(hours=1)
>>> simulation.set_sleep_time(sleep_time)

# Naive datetime (triggers warning):
>>> now = datetime.now()
>>> simulation.set_sleep_time(now + timedelta(hours=1))

# Clear sleep time:
>>> simulation.set_sleep_time(None)
```

```python
set_expire_time(expires_at: datetime.datetime | None) -> None
```

Set when the simulation should be automatically deleted.

Accepts any timezone-aware datetime, which will be automatically
converted to UTC. Naive datetimes (without timezone) will trigger
a warning and assume local timezone.

**Parameters:**

* `expires_at` – Timezone-aware datetime when simulation should expire, or None to clear. Naive datetimes will assume local timezone and emit a warning.

**Example:**

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

# Timezone-aware datetime (recommended):
>>> expire_time = datetime.now(timezone.utc) + timedelta(hours=2)
>>> simulation.set_expire_time(expire_time)

# Naive datetime (triggers warning):
>>> now = datetime.now()
>>> simulation.set_expire_time(now + timedelta(hours=2))

# Clear expiration time:
>>> simulation.set_expire_time(None)
```

```python
create_ztp_script(
    *,
    content: str
) -> ZTPScript
```

Create a ZTP (Zero Touch Provisioning) script for the simulation.

**Parameters:**

* `content` – The content of the ZTP script

**Returns:**

The created ZTPScript instance

**Example:**

```python
>>> script = simulation.create_ztp_script(
...     content='#!/bin/bash\n#CUMULUS-AUTOPROVISIONING\necho "Hello World"'
... )
```

```python
update_ztp_script(
    *,
    content: str
) -> ZTPScript
```

Update the ZTP script for this simulation.

**Parameters:**

* `content` – The new script content

**Returns:**

The updated ZTPScript instance

**Example:**

```python
>>> updated_script = simulation.update_ztp_script(
...     content='#!/bin/bash\n#CUMULUS-AUTOPROVISIONING\necho "Updated"'
... )
```

```python
delete_ztp_script() -> None
```

Delete the ZTP script for this simulation.

After deletion, simulation.ztp\_script will return None.

**Example:**

```python
>>> simulation.delete_ztp_script()
>>> print(simulation.ztp_script)
None
```

```python
export(
    *,
    image_ids: bool = ...,
    topology_format: Literal[JSON] = 'JSON'
) -> dict[str, Any]
```

Export the simulation.

**Parameters:**

* `image_ids` – Whether to include image IDs in the export. If not specified, the API will use its default behavior.
* `topology_format` – Format for the topology in the export. If not specified, the API will use its default behavior.

**Returns:**

Dictionary containing the exported simulation data

**Example:**

```python
# Export with API defaults:
>>> export_data = simulation.export()

# Export with specific options:
>>> export_data = simulation.export(image_ids=True, topology_format='JSON')
```

```python
clone(
    *,
    checkpoint: str | None = ...,
    attempt_start: bool = ...
) -> Simulation
```

Clone/duplicate the simulation.

**Parameters:**

* `checkpoint` – Optional checkpoint ID to clone from. If not specified, Air will find the most recent COMPLETE checkpoint if it exists.
* `attempt_start` – If the simulation should start immediately after cloning

**Returns:**

The cloned Simulation instance

**Example:**

```python
# Simple clone:
>>> cloned_sim = simulation.clone()

# Clone with specific checkpoint:
>>> cloned_sim = simulation.clone(checkpoint='checkpoint-id')

# Clone and start immediately:
>>> cloned_sim = simulation.clone(attempt_start=True)
```

```python
ztp_script: ZTPScript | None
```

Get the simulation's ZTP script if it exists.

**Returns:**

The ZTPScript instance or None if no script exists

**Example:**

```python
>>> if script := simulation.ztp_script:
...     print(script.content)
```

```python
get_history(
    *,
    category: str = ...,
    actor: str = ...,
    search: str = ...,
    ordering: Literal[get_history.actor, get_history.category, created, model, object_id, description] = ...
) -> Iterator[History]
```

Get the historical entries for the simulation.

**Parameters:**

* `category` – Filter by category of the history entries
* `actor` – Filter by actor who performed the actions
* `search` – Search term to filter the history entries
* `ordering` – Order the response by the specified field

**Returns:**

Iterator of History objects for the simulation

**Example:**

```python
# Basic usage with ordering:
>>> for history in simulation.get_history(ordering='created'):
...     print(history.description)

# Search and filter:
>>> for history in simulation.get_history(search='OOB', ordering='category'):
...     print(history.description)
```

```python
nodes: NodeEndpointAPI
```

Query for the related nodes of the simulation.

**Returns:**

NodeEndpointAPI instance filtered for this simulation's nodes

**Example:**

```python
>>> for node in simulation.nodes.list():
...     print(node.name)
```

```python
interfaces: InterfaceEndpointAPI
```

Query for the related interfaces of the simulation.

**Returns:**

InterfaceEndpointAPI instance filtered for this simulation's interfaces

**Example:**

```python
>>> for interface in simulation.interfaces.list():
...     print(interface.name)
```

```python
links: LinkEndpointAPI
```

Query for the related links of the simulation.

**Returns:**

LinkEndpointAPI instance filtered for this simulation's links

**Example:**

```python
>>> for link in simulation.links.list():
...     print(link.interfaces[0].name, link.interfaces[1].name)
```

```python
node_instructions: NodeInstructionEndpointAPI
```

Query for the related node instructions of the simulation.

**Returns:**

NodeInstructionEndpointAPI filtered for this simulation's instructions

**Example:**

```python
>>> for instruction in simulation.node_instructions.list():
...     print(instruction.name, instruction.state)
```

```python
services: ServiceEndpointAPI
```

Query for the related services of the simulation.

**Returns:**

ServiceEndpointAPI instance filtered for this simulation's services

**Example:**

```python
>>> for service in simulation.services.list():
...     print(f'{service.name}: {service.worker_fqdn}:{service.worker_port}')
>>>
>>> # Create service using 'node:interface' string (BC)
>>> service = simulation.services.create(
...     name='SSH', interface='server-1:eth0', dest_port=22
... )
```

```python
checkpoints: CheckpointEndpointAPI
```

Query for the related checkpoints of the simulation.

**Returns:**

CheckpointEndpointAPI instance filtered for this simulation's checkpoints

**Example:**

```python
>>> for cp in simulation.checkpoints.list():
...     print(cp.name, cp.state)
```

```python
create_service(
    *,
    node_name: str,
    interface_name: str,
    node_port: int,
    name: str = ...,
    service_type: Literal[SSH, HTTPS, HTTP, OTHER] = ...
) -> Service
```

Create service using node and interface names.

**Parameters:**

* `node_name` – Node name in this simulation
* `interface_name` – Interface name on the node (e.g., 'eth0', 'swp1')
* `node_port` – Port number on the node
* `name` – Service name (optional)
* `service_type` – Service type - 'SSH', 'HTTPS', 'HTTP', or 'OTHER'

**Returns:**

Service object

**Raises:**

* `ValueError` – If node or interface not found in simulation

**Example:**

```python
>>> service = sim.create_service(
...     node_name='server-1',
...     interface_name='eth0',
...     name='SSH Access',
...     node_port=22,
...     service_type='SSH'
... )
```

```python
node_bulk_assign(
    *,
    nodes: List[NodeAssignmentDataV3]
) -> None
```

Bulk assign configurations to nodes in this simulation.

**Parameters:**

* `nodes` – List of node assignment data containing node, user\_data, and meta\_data

**Example:**

```python
>>> # Bulk assign cloud-init configs to multiple nodes
>>> simulation.node_bulk_assign(
...     nodes=[
...         {'node': 'node1', 'user_data': 'config1'},
...         {'node': 'node2', 'meta_data': 'config2'},
...     ],
... )
```

```python
node_bulk_reset(
    *,
    nodes: List[NodeResetPayload]
) -> None
```

Reset specific nodes within this simulation.

Resetting the node emulates the hardware reset button on physical machines
where the machine is immediately restarted without a clean shutdown of the
operating system. For nodes that are not currently running, this means simply
booting them back up.

**Parameters:**

* `nodes` – List of node reset payloads, each containing a node object or ID

**Example:**

```python
>>> # Reset a single node
>>> simulation.node_bulk_reset(nodes=[{'id': node.id}])

>>> # Reset multiple nodes using node IDs
>>> simulation.node_bulk_reset(
...     nodes=[
...         {'id': 'node-uuid-1'},
...         {'id': 'node-uuid-2'},
...     ],
... )

>>> # Reset all nodes in simulation
>>> nodes_to_reset = [{'id': n} for n in simulation.nodes.list()]
>>> simulation.node_bulk_reset(nodes=nodes_to_reset)
```

```python
node_bulk_rebuild(
    *,
    nodes: List[NodeRebuildPayload],
    checkpoint: str | None = ...
) -> None
```

Rebuild specific nodes within this simulation.

Rebuilding a node means returning the node to either the state of the current
checkpoint of its simulation or its initial, first boot state.
When rebuilding from the initial state, all repeatable instructions
for selected nodes will be applied. All existing instructions
created for the selected nodes which have not yet been completed
will be failed. All existing instructions created for the selected nodes
which have not yet been delivered will be cancelled.

**Parameters:**

* `nodes` – List of node rebuild payloads, each containing a node object or ID
* `checkpoint` – Optional checkpoint ID to rebuild from

**Example:**

```python
>>> # Rebuild a single node
>>> simulation.node_bulk_rebuild(nodes=[{'id': node.id}])

>>> # Rebuild multiple nodes using node IDs
>>> simulation.node_bulk_rebuild(
...     nodes=[
...         {'id': 'node-uuid-1'},
...         {'id': 'node-uuid-2'},
...     ],
... )

>>> # Rebuild all nodes in simulation
>>> nodes_to_rebuild = [{'id': n} for n in simulation.nodes.list()]
>>> simulation.node_bulk_rebuild(nodes=nodes_to_rebuild)
```

```python
class air_sdk.endpoints.simulations.SimulationEndpointAPI
```

**Bases**: `air_sdk.air_model.BaseEndpointAPI[air_sdk.endpoints.simulations.Simulation]`

API client for simulation endpoints.

```python
API_PATH: str
```

```python
model: type[Simulation]
```

```python
create(
    *,
    name: str,
    sleep_at: datetime.datetime | None = ...,
    expires_at: datetime.datetime | None = ...,
    documentation: str | None = ...,
    metadata: str | None = ...
) -> Simulation
```

Create a blank simulation.

**Parameters:**

* `name` – Name for the new simulation
* `sleep_at` – When the simulation should be automatically put to sleep
* `expires_at` – When the simulation should be automatically deleted
* `documentation` – Documentation/description for the simulation
* `metadata` – Custom metadata as a JSON string

**Returns:**

The created Simulation instance

**Example:**

```python
# Simple creation:
>>> simulation = api.simulations.create(name='My Simulation')

# With expiration and documentation:
>>> from datetime import datetime, timedelta, timezone
>>> expires = datetime.now(timezone.utc) + timedelta(days=7)
>>> simulation = api.simulations.create(
...     name='My Simulation',
...     expires_at=expires,
...     documentation='Test simulation'
... )

# With metadata:
>>> simulation = api.simulations.create(
...     name='My Simulation',
...     metadata='{"env": "staging", "owner": "team-a"}'
... )
```

```python
import_from_data(
    *,
    format: str,
    content: dict[str, Any] | str,
    name: str,
    ztp: str | None = ...,
    attempt_start: bool = ...,
    start_timeout: datetime.timedelta | None = ...
) -> Simulation
```

Import a simulation from raw data.

**Parameters:**

* `format` – Format of the content ('JSON' or 'DOT')
* `content` – The topology content (dict for JSON, str for DOT)
* `name` – Name for the new simulation
* `ztp` – Optional ZTP script content
* `attempt_start` – When enabled, waits for the simulation creation to complete and then starts it automatically
* `start_timeout` – Maximum time to wait for simulation creation (default: 120 seconds)

**Returns:**

The imported Simulation instance

**Example:**

```python
# Import from JSON:
>>> simulation = api.simulations.import_from_data(
...     format='JSON', content={'nodes': [...]}, name='My Sim'
... )

# Import and start:
>>> simulation = api.simulations.import_from_data(
...     format='JSON',
...     content={'nodes': [...]},
...     name='My Sim',
...     attempt_start=True
... )

# Import and start with custom timeout:
>>> simulation = api.simulations.import_from_data(
...     format='JSON',
...     content={'nodes': [...]},
...     name='My Sim',
...     attempt_start=True,
...     start_timeout=300
... )
```

```python
import_from_simulation_manifest(
    *,
    simulation_manifest: dict[str, Any] | str | pathlib.Path | io.TextIOBase,
    attempt_start: bool = ...,
    start_timeout: datetime.timedelta | None = ...
) -> Simulation
```

Import simulation from a full JSON manifest file.

The manifest should contain all import parameters including:

* format: 'JSON'
* name: Simulation name
* content: Topology data (for JSON format: dict with 'nodes', 'links',
  'oob', 'netq')
* ztp: Optional ZTP script content

**Parameters:**

* `simulation_manifest` – Full simulation manifest (dict, JSON string, file path, or file handle)
* `attempt_start` – When enabled, waits for the simulation creation to complete and then starts it automatically
* `start_timeout` – Maximum time to wait for simulation creation (default: 120 seconds)

**Returns:**

The created Simulation instance

**Raises:**

* `ValueError` – If manifest is missing required fields
* `FileNotFoundError` – If file path doesn't exist
* `JSONDecodeError` – If JSON content is malformed

**Example:**

```python
# From dict of simulation manifest:
>>> simulation_manifest = {
...     'format': 'JSON',
...     'name': 'My Simulation',
...     'ztp': '#!/bin/bash\necho "ZTP"',
...     'content': {
...         'nodes': {...},
...         'links': [],
...         'oob': True,
...         'netq': False
...     }
... }
>>> simulation = api.simulations.import_from_simulation_manifest(
...     simulation_manifest=simulation_manifest
... )

# With attempt_start:
>>> simulation_manifest = {
...     'format': 'JSON',
...     'name': 'My Simulation',
...     'content': {...}
... }
>>> simulation = api.simulations.import_from_simulation_manifest(
...     simulation_manifest=simulation_manifest,
...     attempt_start=True,
...     start_timeout=300
... )

# From JSON file:
>>> simulation = api.simulations.import_from_simulation_manifest(
...     '/path/to/manifest.json'
... )

# From Path object:
>>> from pathlib import Path
>>> simulation = api.simulations.import_from_simulation_manifest(
...     Path('/path/to/manifest.json')
... )
```

```python
import_from_dot(
    *,
    topology_data: str | pathlib.Path | io.TextIOBase,
    name: str,
    ztp: str | None = ...,
    attempt_start: bool = ...,
    start_timeout: datetime.timedelta | None = ...
) -> Simulation
```

Import simulation from DOT topology file/content.

**Parameters:**

* `topology_data` – DOT topology content (string, file path, Path object, or file handle)
* `name` – Simulation name. If not provided, defaults to the graph name declared in the DOT content
* `ztp` – Optional ZTP script content
* `attempt_start` – When enabled, waits for the simulation creation to complete and then starts it automatically
* `start_timeout` – Maximum time to wait for simulation creation (default: 120 seconds)

**Returns:**

The created Simulation instance

**Raises:**

* `ValueError` – If content is invalid
* `FileNotFoundError` – If file path doesn't exist

**Example:**

```python
# From DOT string:
>>> dot_content = '''
... graph MyNetwork {
...     "server1" [ os="generic/ubuntu2204" ]
...     "switch1" [ os="cumulus/vx:5.11.0" ]
...     "server1":"eth1" -- "switch1":"swp1"
... }
... '''
>>> simulation = api.simulations.import_from_dot(
...     topology_data=dot_content, name='My Simulation'
... )

# Import and start:
>>> simulation = api.simulations.import_from_dot(
...     topology_data=dot_content,
...     name='My Simulation',
...     attempt_start=True
... )

# Import and start with custom timeout:
>>> simulation = api.simulations.import_from_dot(
...     topology_data=dot_content,
...     name='My Simulation',
...     attempt_start=True,
...     start_timeout=300
... )

# From DOT file path:
>>> simulation = api.simulations.import_from_dot(
...     topology_data='/path/to/topology.dot', name='My Simulation'
... )

# With ZTP script:
>>> simulation = api.simulations.import_from_dot(
...     topology_data=dot_content,
...     name='My Simulation',
...     ztp='#!/bin/bash\necho "ZTP"'
... )
```

```python
list(
    *,
    auto_netq_enabled: bool = ...,
    auto_oob_enabled: bool = ...,
    disable_auto_oob_dhcp: bool = ...,
    id: str = ...,
    limit: int = ...,
    name: str = ...,
    offset: int = ...,
    ordering: str = ...,
    search: str = ...,
    state: str = ...
) -> Iterator[Simulation]
```

List all simulations with optional filtering.

**Args:**

auto\_netq\_enabled: Filter by auto NetQ enabled status
auto\_oob\_enabled: Filter by auto OOB enabled status
disable\_auto\_oob\_dhcp: Filter by disable auto OOB DHCP status
id: Filter by simulation ID
limit: Number of results to return per page
name: Filter by simulation name
offset: The initial index from which to return the results
ordering: Order objects by field. Prefix with "-" for desc order
search: Search by name
state: Filter by simulation state (e.g., 'ACTIVE', 'INACTIVE',
'CREATING', 'CLONING', etc.)

**Returns:**

Iterator of Simulation instances

**Example:**

```python
>>> # List all simulations
>>> for sim in api.simulations.list():
...     print(sim.name)
        >>> # Filter by state
        >>> for sim in api.simulations.list(state='ACTIVE'):
        ...     print(sim.name)

        >>> # Search by name
        >>> for sim in api.simulations.list(search='my-sim'):
        ...     print(sim.name)

        >>> # Order by name descending
        >>> for sim in api.simulations.list(ordering='-name'):
        ...     print(sim.name)
```

```python
get(pk: PrimaryKey) -> Simulation
```

Get a specific simulation by ID.

**Parameters:**

* `pk` – The simulation ID (string or UUID)

**Returns:**

The Simulation instance

**Example:**

```python
>>> simulation = api.simulations.get('sim-id')
```

```python
update(
    *,
    simulation: Simulation | PrimaryKey,
    name: str | dataclasses._MISSING_TYPE = ...,
    sleep_at: datetime.datetime | None | dataclasses._MISSING_TYPE = ...,
    expires_at: datetime.datetime | None | dataclasses._MISSING_TYPE = ...,
    documentation: str | None | dataclasses._MISSING_TYPE = ...,
    metadata: str | None | dataclasses._MISSING_TYPE = ...
) -> Simulation
```

Update a simulation's properties.

**Parameters:**

* `simulation` – The simulation to update (Simulation object or ID)
* `name` – New name for the simulation
* `sleep_at` – When the simulation should be automatically put to sleep
* `expires_at` – When the simulation should be automatically deleted
* `documentation` – Documentation/description for the simulation
* `metadata` – Custom metadata as a JSON string

**Returns:**

The updated Simulation instance

**Example:**

```python
# Using Simulation object:
>>> updated_sim = api.simulations.update(
...     simulation=simulation, name='Updated Name'
... )

# Using simulation ID:
>>> updated_sim = api.simulations.update(
...     simulation='sim-123-abc',
...     name='Updated Name',
...     documentation='New docs'
... )

# With metadata:
>>> updated_sim = api.simulations.update(
...     simulation=simulation,
...     metadata='{"env": "production", "version": "1.0"}'
... )
```

```python
export(
    *,
    simulation: Simulation | PrimaryKey,
    image_ids: bool = ...,
    topology_format: Literal[JSON] = 'JSON'
) -> dict[str, Any]
```

Export a simulation.

**Parameters:**

* `simulation` – The simulation to export (Simulation object or simulation ID)
* `image_ids` – Whether to include image IDs in the export
* `topology_format` – Format for the topology in the export

**Returns:**

Dictionary containing the exported simulation data

**Example:**

```python
# Using Simulation object:
>>> export_data = api.simulations.export(simulation=simulation)

# Using simulation ID:
>>> export_data = api.simulations.export(simulation='sim-123-abc')

# With optional parameters:
>>> export_data = api.simulations.export(
...     simulation=simulation, image_ids=True, topology_format='JSON'
... )
```

```python
clone(
    *,
    simulation: Simulation | PrimaryKey,
    checkpoint: str | None = ...,
    attempt_start: bool = ...
) -> Simulation
```

Clone/duplicate a simulation.

**Parameters:**

* `simulation` – The simulation to clone (Simulation object or simulation ID)
* `checkpoint` – Optional checkpoint ID to clone from. If not specified, Air will find the most recent COMPLETE checkpoint if it exists.
* `attempt_start` – If the simulation should start immediately after cloning

**Returns:**

The cloned Simulation instance

**Example:**

```python
# Using Simulation object:
>>> cloned_sim = api.simulations.clone(simulation=sim)

# Using simulation ID:
>>> cloned_sim = api.simulations.clone(simulation='sim-123-abc')

# Clone with checkpoint:
>>> cloned_sim = api.simulations.clone(
...     simulation=sim, checkpoint='checkpoint-id'
... )

# Clone and start immediately:
>>> cloned_sim = api.simulations.clone(simulation=sim, attempt_start=True)
```

```python
enable_auto_oob(
    *,
    simulation: Simulation | PrimaryKey,
    disable_auto_oob_dhcp: bool = ...
) -> None
```

Enable automatic Out-of-band management for a simulation.

**Parameters:**

* `simulation` – The simulation object or simulation ID
* `disable_auto_oob_dhcp` – If True, disable DHCP on the OOB management network

**Example:**

```python
# Enable OOB with DHCP (using simulation object):
>>> api.simulations.enable_auto_oob(simulation=simulation)

# Enable OOB using simulation ID:
>>> api.simulations.enable_auto_oob(simulation='uuid-123')

# Enable OOB without DHCP:
>>> api.simulations.enable_auto_oob(
...     simulation=simulation, disable_auto_oob_dhcp=True
... )
```

```python
disable_auto_oob(
    *,
    simulation: Simulation | PrimaryKey
) -> None
```

Disable automatic Out-of-band management for a simulation.

**Parameters:**

* `simulation` – The simulation object or simulation ID

**Example:**

```python
# Using simulation object:
>>> api.simulations.disable_auto_oob(simulation=simulation)

# Using simulation ID:
>>> api.simulations.disable_auto_oob(simulation='uuid-123')
```

```python
enable_auto_netq(
    *,
    simulation: Simulation | PrimaryKey
) -> None
```

Enable automatic NetQ for a simulation.

**Parameters:**

* `simulation` – The simulation object or simulation ID

**Example:**

```python
# Using simulation object:
>>> api.simulations.enable_auto_netq(simulation=simulation)

# Using simulation ID:
>>> api.simulations.enable_auto_netq(simulation='uuid-123')
```

```python
disable_auto_netq(
    *,
    simulation: Simulation | PrimaryKey
) -> None
```

Disable automatic NetQ for a simulation.

**Parameters:**

* `simulation` – The simulation object or simulation ID

**Example:**

```python
# Using simulation object:
>>> api.simulations.disable_auto_netq(simulation=simulation)

# Using simulation ID:
>>> api.simulations.disable_auto_netq(simulation='uuid-123')
```

```python
start(
    *,
    simulation: Simulation | PrimaryKey,
    checkpoint: str | None = ...
) -> None
```

Start a simulation.

**Parameters:**

* `simulation` – The simulation object or simulation ID to start
* `checkpoint` – Optional checkpoint ID to start from. If not specified, the API will use its default behavior (typically uses the most recent checkpoint if available). If explicitly set to None, starts from clean state (rebuild). If a string, starts from the specified checkpoint.

**Example:**

```python
# Normal start (API determines behavior):
>>> api.simulations.start(simulation=simulation)

# Start using simulation ID:
>>> api.simulations.start(simulation='uuid-123')

# Start from specific checkpoint:
>>> api.simulations.start(simulation=simulation, checkpoint='checkpoint-id')

# Rebuild (start from clean state, no checkpoint):
>>> api.simulations.start(simulation=simulation, checkpoint=None)
```

```python
rebuild(
    *,
    simulation: Simulation | PrimaryKey,
    checkpoint: str | None = ...
) -> None
```

Rebuild a simulation from a given checkpoint.

Tears down the simulation and starts it from the given checkpoint.
If no checkpoint is provided, the simulation will be rebuilt from the clean state.

**Parameters:**

* `simulation` – The simulation object or simulation ID to rebuild
* `checkpoint` – Optional checkpoint ID to rebuild from. If not specified, the API will use its default behavior (the current checkpoint the simulation is running off of). If explicitly set to None, starts from clean state (rebuild). If a string, starts from the specified checkpoint.

**Example:**

```python
# Rebuild simulation from specific checkpoint:
>>> api.simulations.rebuild(simulation=simulation, checkpoint='checkpoint-id')

# Rebuild from clean state (no checkpoint):
>>> api.simulations.rebuild(simulation=simulation, checkpoint=None)

# Rebuild using simulation ID:
>>> api.simulations.rebuild(simulation='uuid-123')
```

```python
shutdown(
    *,
    simulation: Simulation | PrimaryKey,
    create_checkpoint: bool = ...
) -> None
```

Shut down a simulation.

**Parameters:**

* `simulation` – The simulation object or simulation ID to shut down
* `create_checkpoint` – Whether to create a checkpoint before shutting down. If not specified, the API will use its default behavior.

**Example:**

```python
# Normal shutdown (API determines behavior):
>>> api.simulations.shutdown(simulation=simulation)

# Shutdown using simulation ID:
>>> api.simulations.shutdown(simulation='uuid-123')

# Explicitly create checkpoint before shutdown:
>>> api.simulations.shutdown(simulation=simulation, create_checkpoint=True)

# Explicitly don't create checkpoint:
>>> api.simulations.shutdown(simulation=simulation, create_checkpoint=False)
```

```python
create_service(
    *,
    simulation: Simulation | PrimaryKey,
    node_name: str,
    interface_name: str,
    node_port: int,
    name: str = ...,
    service_type: Literal[SSH, HTTPS, HTTP, OTHER] = ...
) -> Service
```

Create service for a simulation by resolving node and interface names.

**Parameters:**

* `simulation` – Simulation ID or object
* `node_name` – Node name in the simulation
* `interface_name` – Interface name on the node (e.g., 'eth0', 'swp1')
* `node_port` – Port number on the node
* `name` – Service name (optional)
* `service_type` – Service type - 'SSH', 'HTTPS', 'HTTP', or 'OTHER'

**Returns:**

Service object

**Raises:**

* `ValueError` – If node or interface not found in simulation

**Example:**

```python
>>> service = api.simulations.create_service(
...     simulation='sim-id',
...     node_name='server-1',
...     interface_name='eth0',
...     node_port=22,
...     service_type='SSH'
... )
```

```python
parse(
    *,
    topology_data: str,
    source_format: str,
    destination_format: str
) -> dict[str, Any]
```

Parse topology content between different formats.

Convert topology data between different formats (e.g., DOT to JSON).

**Parameters:**

* `topology_data` – The topology content to parse
* `source_format` – The format to parse the topology from (e.g., 'DOT').
* `destination_format` – The format to parse the topology to (e.g., 'JSON').

**Returns:**

Parsed topology data as a dictionary

**Example:**

```python
>>> dot_content = '''
... graph MyNetwork {
...     "node-1" [ os="generic/ubuntu2204" cpu=2 ]
...     "node-2" [ os="generic/ubuntu2204" memory=2048 ]
...     "node-1":"eth1" -- "node-2":"eth1"
... }
... '''
>>> # Convert DOT to JSON
>>> parsed = api.simulations.parse(
...     topology_data=dot_content,
...     source_format='DOT',
...     destination_format='JSON',
... )
```

```python
node_bulk_assign(
    *,
    simulation: Simulation | PrimaryKey,
    nodes: List[NodeAssignmentDataV3]
) -> None
```

Bulk assign configurations to nodes in given simulation.

**Parameters:**

* `simulation` – The simulation to bulk assign to
* `nodes` – List of node assignment data containing node, user\_data, and meta\_data

**Example:**

```python
>>> # Bulk assign cloud-init configs to multiple nodes
>>> api.simulations.node_bulk_assign(
...     simulation=simulation,
...     nodes=[
...         {'node': 'node1', 'user_data': 'config1'},
...         {'node': 'node2', 'meta_data': 'config2'},
...     ],
... )
```

```python
node_bulk_reset(
    *,
    simulation: Simulation | PrimaryKey,
    nodes: List[NodeResetPayload]
) -> None
```

Reset specific nodes within a simulation.

Resetting the node emulates the hardware reset button on physical machines
where the machine is immediately restarted without a clean shutdown of the
operating system. For nodes that are not currently running, this means simply
booting them back up.

**Parameters:**

* `simulation` – The simulation object or simulation ID containing the nodes
* `nodes` – List of node reset payloads, each containing a node object or ID

**Example:**

```python
>>> # Reset a single node using node object
>>> api.simulations.node_bulk_reset(
...     simulation=simulation,
...     nodes=[{'id': node}],
... )

>>> # Reset multiple nodes using node IDs
>>> api.simulations.node_bulk_reset(
...     simulation='sim-uuid-123',
...     nodes=[
...         {'id': 'node-uuid-1'},
...         {'id': 'node-uuid-2'},
...     ],
... )

>>> # Reset nodes retrieved from simulation
>>> nodes = [{'id': n} for n in simulation.nodes.list()]
>>> api.simulations.node_bulk_reset(simulation=simulation, nodes=nodes)
```

```python
node_bulk_rebuild(
    *,
    simulation: Simulation | PrimaryKey,
    nodes: List[NodeRebuildPayload],
    checkpoint: str | None = ...
) -> None
```

Rebuild specific nodes within a simulation.

Rebuilding a node means returning the node to either the state of the current
checkpoint of its simulation or its initial, first boot state.
When rebuilding from the initial state, all repeatable instructions
for selected nodes will be applied. All existing instruction
created for the selected nodes which have not yet been completed
will be failed. All existing instructions created for the selected nodes
which have not yet been delivered will be cancelled.

**Parameters:**

* `simulation` – The simulation object or simulation ID containing the nodes
* `nodes` – List of node rebuild payloads, each containing a node object or ID
* `checkpoint` – Optional checkpoint ID to rebuild from

**Example:**

```python
>>> # Rebuild a single node using node object
>>> api.simulations.node_bulk_rebuild(
...     simulation=simulation,
...     nodes=[{'id': node}],
... )

>>> # Rebuild multiple nodes using node IDs
>>> api.simulations.node_bulk_rebuild(
...     simulation='sim-uuid-123',
...     nodes=[
...         {'id': 'node-uuid-1'},
...         {'id': 'node-uuid-2'},
...     ],
... )
```