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

# Nodes

```python
# Imports (run once)
from air_sdk import AirApi
from air_sdk.endpoints.images import Image
from air_sdk.endpoints.nodes import Node
from air_sdk.endpoints.simulations import Simulation
```

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

## CREATE

We can create new nodes for a simulation by using the `api.nodes.create` method:

```python
sim: Simulation = api.simulations.create(name='Blank Simulation')
ubuntu_2204 = next(api.images.list(search='generic/ubuntu2204'))

node: Node = api.nodes.create(
    simulation=sim,
    image=ubuntu_2204,
    name='ubuntu-server',
)
node.dict()
```

```
{'id': 'a06bad49-40bb-4ded-a24c-5f182a0cdba0',
 'created': datetime.datetime(2026, 7, 22, 9, 40, 8, 532132, tzinfo=datetime.timezone.utc),
 'modified': datetime.datetime(2026, 7, 22, 9, 40, 8, 532153, tzinfo=datetime.timezone.utc),
 'name': 'ubuntu-server',
 'simulation': '98b8806b-f1fa-442a-9ff5-d642853842fc',
 'image': '8674741d-5bdf-417f-bc78-7bda9ad4d101',
 'category': '',
 'state': 'INACTIVE',
 'status_from_worker': '',
 'split_options': None,
 'cpu': 1,
 'memory': 1024,
 'storage': 10,
 'pos_x': 0,
 'pos_y': 0,
 'cdrom': None,
 'storage_pci': None,
 'labels': {},
 'metadata': '{"mgmt_mac": "48:B0:2D:00:00:00"}',
 'advanced': {'nic_model': 'virtio',
  'cpu_mode': 'custom',
  'cpu_options': [],
  'secureboot': False,
  'uefi': False,
  'boot': 'hd'},
 'management_interfaces': {'eth0': {'ip': None,
   'mac_address': '48:B0:2D:00:00:00'}}}
```

Nodes can also be created off of an existing `Simulation` instance:

```python
sim: Simulation = api.simulations.create(name='Blank Simulation')
ubuntu_2204 = next(api.images.list(search='generic/ubuntu2204'))

# You do not have to specify `simulation=sim` in the payload when using this method.
node: Node = sim.nodes.create(name='new-node', image=ubuntu_2204)
node.dict()
```

```
{'id': '04f8e68a-6bb1-4de9-be1b-6e5a457084ca',
 'created': datetime.datetime(2026, 7, 22, 9, 37, 53, 946807, tzinfo=datetime.timezone.utc),
 'modified': datetime.datetime(2026, 7, 22, 9, 37, 53, 946827, tzinfo=datetime.timezone.utc),
 'name': 'new-node',
 'simulation': '59b873b9-e94e-460a-914e-1233e86807ab',
 'image': '8674741d-5bdf-417f-bc78-7bda9ad4d101',
 'category': '',
 'state': 'INACTIVE',
 'status_from_worker': '',
 'split_options': None,
 'cpu': 1,
 'memory': 1024,
 'storage': 10,
 'pos_x': 0,
 'pos_y': 0,
 'cdrom': None,
 'storage_pci': None,
 'labels': {},
 'metadata': '{"mgmt_mac": "48:B0:2D:00:00:00"}',
 'advanced': {'nic_model': 'virtio',
  'cpu_mode': 'custom',
  'cpu_options': [],
  'secureboot': False,
  'uefi': False,
  'boot': 'hd'},
 'management_interfaces': {'eth0': {'ip': None,
   'mac_address': '48:B0:2D:00:00:00'}}}
```

## GET

How to list, filter, order, and search for nodes of a simulation.

```python
ubuntu_2204: Image = next(api.images.list(search='generic/ubuntu2204'))
cumulus_5_6_0: Image = next(api.images.list(search='cumulus-vx-5.6.0'))
sim: Simulation = api.simulations.create(name='Blank Simulation')
```

```python
# Create nodes with various specifications
sim.nodes.create(name='ubuntu-1', image=ubuntu_2204)
sim.nodes.create(name='ubuntu-2', image=ubuntu_2204)
sim.nodes.create(name='ubuntu-12', image=ubuntu_2204)
sim.nodes.create(name='special-node', image=ubuntu_2204)
sim.nodes.create(name='node14', image=cumulus_5_6_0)
sim.nodes.create(name='node15', image=cumulus_5_6_0)
sim.nodes.create(name='node16', image=cumulus_5_6_0)

for node in sim.nodes.list():
    print(node)
```

```
Node(id='42917bde-000a-4209-a20b-59db0c15b1a1', name='ubuntu-1')
Node(id='552b72bd-e4c5-4226-b50e-0e763c7890b8', name='ubuntu-2')
Node(id='c2903bfe-fa0b-43ec-ae75-7faf80f1f049', name='ubuntu-12')
Node(id='7f6772aa-76ef-4012-a2e0-e6d30ceb78a4', name='special-node')
Node(id='f61db084-99da-4928-bdb3-7bbd5950416e', name='node14')
Node(id='1a77d4bd-f533-48a7-a169-1415d52d8d91', name='node15')
Node(id='4abe2036-b4d1-438e-ad3b-9c236fd32e47', name='node16')
```

#### Order nodes by specific fields

```python
for node in sim.nodes.list(ordering='name'):
    print(node.name)
```

```
node14
node15
node16
special-node
ubuntu-1
ubuntu-12
ubuntu-2
```

#### Search for nodes by name

```python
for node in sim.nodes.list(search='node'):
    print(node.name)
```

```
node14
node15
node16
```

#### Filter node by specific properties

```python
for node in sim.nodes.list(image=cumulus_5_6_0):
    print(node.name, node.image.name)
```

```
node14 cumulus-vx-5.6.0
node15 cumulus-vx-5.6.0
node16 cumulus-vx-5.6.0
```

This can be used to obtain a specific node by `name`

```python
list(sim.nodes.list(name='special-node'))
```

```
[Node(id='7f6772aa-76ef-4012-a2e0-e6d30ceb78a4', name='special-node')]
```