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

# Export a simulation to a desired topology format

GET https://api.dsx-air.nvidia.com/api/v3/simulations/{id}/export/

Simulations can be exported to supported topology formats via this endpoint. Export behavior can be controlled by providing query parameters.

**Required scope:** `air:simulation_read` (roles: `air_org_admin`, `air_user`)

**Alternative:** role `air_trainee` also grants access.

Reference: https://docs.nvidia.com/dsx-air/api-reference/simulations/api-v-3-simulations-export-retrieve

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `id` (string, required) — A UUID string identifying this simulation.

### Query parameters

- `image_ids` (boolean, optional, default: false) — Set this flag in order to return image IDs instead of names.
- `include_instructions` (enum, optional, default: NONE) — Which client-created instructions to include. Instructions on child plugin nodes and OOB switches are never included, because you cannot import them. - `NONE`: Do not include instructions. - `REPEATABLE`: Include instructions with `created_by_client` and `run_again_on_rebuild` set to true. - `REPEATABLE_OR_NOT_READY`: Include instructions with `created_by_client` set to true and either `run_again_on_rebuild` set to true or `state` set to `NOT_READY`. This option includes all instructions which would be executed if the simulation was booted without a checkpoint right now.
  - Allowed values: `NONE`, `REPEATABLE`, `REPEATABLE_OR_NOT_READY`
- `include_services` (boolean, optional, default: false) — Include services in the export.
- `topology_format` (enum, required) — Desired output format.
  - Allowed values: `JSON`

## Response

### 200

- `object`
  - TopologyFormatFullJSON
    - `format` (enum, required) — * `JSON` - JSON format
      - Allowed values: `JSON`
    - `content` (object, required) — Representation of a network topology.
      - `nodes` (map from string to object, required) — Nodes which are part of the topology.
        - `os` (string, required) — Name / UUID of an image to use as a disk.
        - `cpu` (integer, optional) — Amount of CPU cores to dedicate to the node.
        - `memory` (integer, optional) — Amount of memory (in MiB) to dedicate to the node.
        - `storage` (integer, optional) — Amount of disk space (in GB) to dedicate to the node.
        - `positioning` (object, optional) — Node positioning as seen in the UI.
          - `x` (integer, required) — Node's X coordinate in the topology.
          - `y` (integer, required) — Node's Y coordinate in the topology.
        - `nic_model` (enum, optional, default: virtio) — Indicates the model to use for the node's network interfaces. * `virtio` - VirtIO * `e1000` - Intel E1000
          - Allowed values: `virtio`, `e1000`
        - `cpu_mode` (enum, optional, default: custom) — Indicates the CPU mode of the node. Can only be set for entities without an `emulation_type` set. * `custom` - Custom CPU mode which can include custom CPU options. * `host-model` - CPU mode which attempts to select a CPU model resembling the hypervisor's CPU model as closely as possible. * `host-passthrough` - CPU mode which exposes all details of the hypervisor's CPU model.
          - Allowed values: `custom`, `host-model`, `host-passthrough`
        - `cpu_options` (list of enum, optional) — Indicates the CPU options of the node. CPU mode must be set to `custom` for CPU options to be used. Can only be set for entities without an `emulation_type` set.
          - Allowed values: `ssse3`, `sse4.1`, `sse4.2`, `popcnt`
        - `secureboot` (boolean, optional, default: false) — Indicates whether the node should perform a SecureBoot. UEFI must be enabled for SecureBoot to be used. Can only be set for entities without an `emulation_type` set.
        - `cdrom` (string, optional) — Name / UUID of an image to put in the node's CD ROM.
        - `labels` (object, optional, nullable) — Labels (attributes) of the node.
          - `group` (string, optional) — The group of the node.
          - `model` (string, optional) — The model of the node.
          - `sku` (string, optional) — The SKU of the node.
          - `rack_name` (string, optional) — The name of the rack the node is part of.
          - `rack_unit` (integer, optional) — The unit number within a rack for the node.
          - `scalable_unit` (integer, optional) — The scalable unit number that the node belongs to.
          - `rail_index` (integer, optional) — The rail index that the node belongs to.
          - `data_hall` (string, optional) — The name of the data hall that the node is part of.
          - `tray_index` (integer, optional) — The tray index of the node.
          - `role` (string, optional) — The role of the node, e.g. leaf.
          - `pod` (integer, optional) — The pod number that the node belongs to.
          - `superspine_group` (integer, optional) — The superspine group number that the node belongs to.
          - `plane_id` (integer, optional) — Plane identifier in a multi-plane fabric.
        - `management_mac` (string, optional) — MAC address to assign to the management interface of the node.
        - `management_ip` (string, optional) — IP address for the management interface on the OOB network. Must be within 192.168.0.0/16 and not end in .255 (broadcast). Using .254 requires defining a custom gateway in oob.subnets. If not provided, IP is auto-assigned via DHCP when OOB is enabled. When OOB is disabled, this value is stored for documentation purposes.
        - `management_interfaces` (map from string to object, optional) — Dict mapping interface names (e.g. "eth0", "eth1") to management address info with optional keys "ip" (IPv4) and "mac_address". Mutually exclusive with management_ip and management_mac.
          - `ip` (string, optional, nullable) — IPv4 address for this management interface on the OOB network. Must be within 192.168.0.0/16 and not end in .255 (broadcast). Set to `null` to opt this interface out of OOB-managed DHCP (interface is still wired to the leaf switch, but no ManagementAddress or dhcpd host entry is created).
          - `mac_address` (string, optional) — Unicast MAC address for this management interface.
        - `oob` (boolean, optional, default: false) — Whether this node is part of a custom management network. Nodes which have this field set to `true` will boot before the rest. In order to set this flag, default Out-of-Band management network must be disabled.
        - `storage_pci` (map from string to object, optional, nullable) — Storage PCI entities which are connected to this node.
          - `type` (enum, required) — Type of the storage PCI device * `NVME` - NVMe SSD Drive
            - Allowed values: `NVME`
          - `size` (integer, required) — Size of the storage PCI device in GB
          - `name` (string, optional) — Name of the storage PCI device. If not provided, a default name will be assigned in the format `nvme-<index+1>`. The name must contain only letters, numbers, and hyphens and be less than 20 characters
        - `emulation_type` (string, optional, nullable) — Hardware emulation type for this node.
        - `model` (string, optional) — When setting `emulation_type`, the hardware model that is being emulated.
        - `simulator_image` (string, optional) — When setting `emulation_type`, explicit name / UUID of an image to use as a simulator image.
        - `port_type` (string, optional) — When setting `emulation_type`, the type of port that is being emulated.
        - `number_of_ports` (integer, optional) — When setting `emulation_type`, the explicit amount of ports that is requested to be set for the model.
        - `network_pci` (map from string to object, optional) — When setting `emulation_type`, network PCI entities which are connected to this node.
          - `emulation_type` (string, required) — Hardware emulation type for this network PCI entity.
          - `nic_model` (enum, optional, default: virtio) — Indicates the model to use for the node's network interfaces. * `virtio` - VirtIO * `e1000` - Intel E1000
            - Allowed values: `virtio`, `e1000`
          - `model` (string, optional) — Hardware model for this network PCI entity.
          - `pci_address` (string, optional) — Address of this PCI entity, in BDF notation (e.g 0000:1a:00.0).
          - `port_type` (string, optional) — Type of port emulated by this device.
          - `number_of_ports` (integer, optional) — The explicit amount of ports that is requested to be set for the model
          - `os` (string, optional) — Name / UUID of a image to use as a disk for the entity.
          - `cpu` (integer, optional) — When `os` is set, amount of CPU cores to dedicate to the entity.
          - `memory` (integer, optional) — When `os` is set, amount of memory (in MiB) to dedicate to the entity.
          - `storage` (integer, optional) — When `os` is set, amount of disk space (in GB) to dedicate to the entity.
          - `positioning` (object, optional) — When `os` is set, entity positioning as seen in the UI.
            - `x` (integer, required) — Node's X coordinate in the topology.
            - `y` (integer, required) — Node's Y coordinate in the topology.
          - `cpu_arch` (enum, optional) — When `os` is set, desired CPU architecture of emulated hardware. * `x86` - x86 * `ARM` - ARM
            - Allowed values: `x86`, `ARM`
          - `simulator_image` (string, optional) — When `os` is set, explicit name / UUID of an image to use as a simulator image.
          - `management_mac` (string, optional) — When `os` is set and OOB is enabled, MAC address for the management interface (eth0).
          - `management_ip` (string, optional) — When `os` is set and OOB is enabled, IP address for the management interface on the OOB network. Must be within 192.168.0.0/16 and not end in .255 (broadcast).
          - `management_interfaces` (map from string to object, optional) — When `os` is set and OOB is enabled, dict mapping interface names (e.g. "eth0", "eth1") to management address info with optional keys "ip" (IPv4) and "mac_address". Mutually exclusive with management_ip and management_mac.
            - `ip` (string, optional, nullable) — IPv4 address for this management interface on the OOB network. Must be within 192.168.0.0/16 and not end in .255 (broadcast). Set to `null` to opt this interface out of OOB-managed DHCP (interface is still wired to the leaf switch, but no ManagementAddress or dhcpd host entry is created).
            - `mac_address` (string, optional) — Unicast MAC address for this management interface.
          - `os_template_version` (string, optional) — When `os` is set, override the OS template version resolved from the OS Image manifest pin.
          - `platform_information_version` (string, optional) — When `os` is set, override the platform information version resolved from the OS Image manifest pin.
          - `default_split` (string, optional) — Override the default port split defined by the node's resolved platform information. Must be one of its split options.
        - `os_template_version` (string, optional) — When setting `emulation_type`, override the OS template version resolved from the OS Image manifest pin.
        - `platform_information_version` (string, optional) — When setting `emulation_type`, override the platform information version resolved from the OS Image manifest pin.
        - `default_split` (string, optional) — Override the default port split defined by the node's resolved platform information. Must be one of its split options.
        - `pxehost` (boolean, optional, default: false) — Whether to perform a PXE (network) boot.
        - `boot` (list of enum, optional) — Boot device(s) for the node. Accepts a single device (e.g. 'hd', 'network') or a list of up to 3 unique devices for ordered fall-through (e.g. ['network', 'hd']).
          - Allowed values: `hd`, `network`, `cdrom`
        - `features` (object, optional) — Legacy field for fields which are now in `advanced` field.
          - `uefi` (boolean, optional, default: false) — Indicates whether the node should use UEFI. Can only be set for entities without an `emulation_type` set.
      - `links` (list of list of object or enum or object, optional) — Connections between nodes defined in the topology.
        - object
          - `interface` (string, required) — Name for the network interface. Must not be `eth0`.
          - `node` (string, required) — Node that hosts this interface.
          - `mac` (string, optional) — MAC address to assign to this interface. If not specified, one will be generated.
          - `network_pci` (string, optional) — Name for the network PCI entity this interface resides on.
          - `split` (string, optional) — Breakout (split) factor of the interface: the platform port map's split bucket the interface belongs to. Omit or set to `null` to use the platform's default split.
          - `interface_role` (string, optional) — The role of the interface.
          - `scalable_unit` (integer, optional) — The scalable unit number that the node belongs to.
        - object
          - `cable_length` (string, optional) — The length of the cable connecting the interfaces.
      - `oob` (object, optional) — Configuration of default Out-of-Band management network.
        - `nodes` (object, optional) — Configuration of individual Out-of-Band management nodes.
          - `oob-mgmt-server` (object, optional) — Configuration for an Out-of-Band node.
            - `cpu` (integer, optional) — Amount of CPU cores to dedicate to the node.
            - `memory` (integer, optional) — Amount of memory (in MiB) to dedicate to the node.
            - `storage` (integer, optional) — Amount of disk space (in GB) to dedicate to the node.
            - `positioning` (object, optional) — Node positioning as seen in the UI.
          - `oob-mgmt-switch` (object, optional) — Configuration for an Out-of-Band node.
            - `cpu` (integer, optional) — Amount of CPU cores to dedicate to the node.
            - `memory` (integer, optional) — Amount of memory (in MiB) to dedicate to the node.
            - `storage` (integer, optional) — Amount of disk space (in GB) to dedicate to the node.
            - `positioning` (object, optional) — Node positioning as seen in the UI.
        - `enable_dhcp` (boolean, optional, default: true) — If the default DHCP service on the automatic Out-of-Band management network should be enabled.
        - `subnets` (map from string to object, optional) — Custom gateway IP configurations for specific subnets. If not provided, default .254 addresses are used for all subnets. Example: \{"192.168.200.0/24": \{"gateway\_ip": "192.168.200.1"}}
          - `gateway_ip` (string, required) — Custom gateway IP address for this subnet.
      - `instructions` (list of object or object or object, optional) — Instructions to run on nodes in the topology. Optional. You cannot import instructions for child plugin nodes or OOB switches.
        - TopologyFormatInitInstruction
          - `node` (string, required) — Name of the node that receives this instruction.
          - `executor` (enum, required) — Must be `init` to select this instruction type. * `init` - init
            - Allowed values: `init`
          - `data` (object, required) — Data on what hostname should be assigned to the node when it initializes.
            - `hostname` (string, required) — Hostname to assign to the node when it initializes.
          - `name` (string, optional) — A descriptive name for the instruction. Optional.
          - `run_again_on_rebuild` (boolean, optional, default: false) — If `true`, the instruction runs again every time the node is rebuilt. Defaults to `false`.
          - `wait_for_network` (boolean, optional, default: true) — If `true`, delivery waits until the node is reachable on the network. Defaults to `true`.
          - `reachability_check` (object, optional, nullable) — Settings for the reachability check used when `wait_for_network` is `true`.
            - `reachability_ip` (string, optional, nullable) — IPv4 address to check for reachability. If automatic OOB is enabled and no address is given, the `oob-mgmt-server` address is used instead.
            - `timeout` (integer, optional, default: 480) — How long to wait for the reachability check, in seconds.
            - `vrf` (string, optional, nullable) — Name of the VRF to check reachability in. Optional.
        - TopologyFormatShellInstruction
          - `node` (string, required) — Name of the node that receives this instruction.
          - `executor` (enum, required) — Must be `shell` to select this instruction type. * `shell` - shell
            - Allowed values: `shell`
          - `data` (object, required) — Information on shell commands to be run on the node.
            - `commands` (list of string, required) — List of shell commands to run on the node, in order.
          - `name` (string, optional) — A descriptive name for the instruction. Optional.
          - `run_again_on_rebuild` (boolean, optional, default: false) — If `true`, the instruction runs again every time the node is rebuilt. Defaults to `false`.
          - `wait_for_network` (boolean, optional, default: true) — If `true`, delivery waits until the node is reachable on the network. Defaults to `true`.
          - `reachability_check` (object, optional, nullable) — Settings for the reachability check used when `wait_for_network` is `true`.
            - `reachability_ip` (string, optional, nullable) — IPv4 address to check for reachability. If automatic OOB is enabled and no address is given, the `oob-mgmt-server` address is used instead.
            - `timeout` (integer, optional, default: 480) — How long to wait for the reachability check, in seconds.
            - `vrf` (string, optional, nullable) — Name of the VRF to check reachability in. Optional.
        - TopologyFormatFileInstruction
          - `node` (string, required) — Name of the node that receives this instruction.
          - `executor` (enum, required) — Must be `file` to select this instruction type. * `file` - file
            - Allowed values: `file`
          - `data` (object, required) — Information needed to write files to the node.
            - `files` (list of object, required) — List of files to write to the node.
            - `post_commands` (list of string, optional) — List of shell commands to run, in order, after the files are written.
          - `name` (string, optional) — A descriptive name for the instruction. Optional.
          - `run_again_on_rebuild` (boolean, optional, default: false) — If `true`, the instruction runs again every time the node is rebuilt. Defaults to `false`.
          - `wait_for_network` (boolean, optional, default: true) — If `true`, delivery waits until the node is reachable on the network. Defaults to `true`.
          - `reachability_check` (object, optional, nullable) — Settings for the reachability check used when `wait_for_network` is `true`.
            - `reachability_ip` (string, optional, nullable) — IPv4 address to check for reachability. If automatic OOB is enabled and no address is given, the `oob-mgmt-server` address is used instead.
            - `timeout` (integer, optional, default: 480) — How long to wait for the reachability check, in seconds.
            - `vrf` (string, optional, nullable) — Name of the VRF to check reachability in. Optional.
      - `services` (list of object, optional) — Services exposed on the topology's outbound interfaces. Optional; up to `252` services are allowed per interface.
        - `node` (string, required) — Name of the node that hosts the interface for this service.
        - `interface` (string, required) — Name of the interface that exposes this service. Must be the source of a link to `outbound`.
        - `node_port` (integer, required) — Port number the service listens on, from `1` to `65535`. Must be unique on this interface.
        - `name` (string, optional) — A descriptive name for the service. Optional.
        - `service_type` (enum, optional, default: OTHER) — The type of service, for example `SSH` or `HTTPS`. Defaults to `OTHER`. * `SSH` - SSH * `HTTPS` - HTTPS * `HTTP` - HTTP * `OTHER` - Other
          - Allowed values: `SSH`, `HTTPS`, `HTTP`, `OTHER`
    - `name` (string, required) — Name of the simulation.
    - `ztp` (string, optional, nullable) — Global ZTP (Zero Touch Provisioning) script to apply to all nodes.

## Errors

### 403 Forbidden Error

- `detail` (string, required) — Description of an error.
- `request_id` (string, required, nullable) — ID assigned to the request which encountered the error. Should be provided when opening a support case.

### 404 Not Found Error

- `request_id` (string, required, nullable) — ID assigned to the request which encountered the error. Should be provided when opening a support case.
- `detail` (string, optional, default: No object matches the given query.) — Description of an error.

### 500 Internal Server Error

- `request_id` (string, required, nullable) — ID assigned to the request which encountered the error. Should be provided when opening a support case.
- `code` (string, required) — Error code which identifies the error. Should be provided when opening a support case.
- `detail` (string, optional, default: An unexpected error has occurred. Please contact NVIDIA Air support for further assistance.) — Description of an error.

## Examples

**Response**

```json
{
  "content": {
    "instructions": [
      {
        "data": {
          "hostname": "string"
        },
        "executor": "init",
        "name": "string",
        "node": "string",
        "reachability_check": {
          "reachability_ip": "string",
          "timeout": 480,
          "vrf": "string"
        },
        "run_again_on_rebuild": false,
        "wait_for_network": true
      }
    ],
    "links": [
      [
        {
          "interface": "interface1",
          "interface_role": "interface_role1",
          "mac": "mac1",
          "network_pci": "network_pci1",
          "node": "node1",
          "scalable_unit": 1,
          "split": "split1"
        },
        {
          "interface": "interface2",
          "interface_role": "interface_role2",
          "mac": "mac2",
          "network_pci": "network_pci2",
          "node": "node2",
          "scalable_unit": 1,
          "split": "split2"
        }
      ],
      [
        {
          "interface": "interface1",
          "interface_role": "interface_role1",
          "mac": "mac1",
          "network_pci": "network_pci1",
          "node": "node1",
          "scalable_unit": 1,
          "split": "split1"
        },
        "outbound"
      ],
      [
        {
          "interface": "interface1",
          "interface_role": "interface_role1",
          "mac": "mac1",
          "network_pci": "network_pci1",
          "node": "node1",
          "scalable_unit": 1,
          "split": "split1"
        },
        {
          "interface": "interface2",
          "interface_role": "interface_role2",
          "mac": "mac2",
          "network_pci": "network_pci2",
          "node": "node2",
          "scalable_unit": 1,
          "split": "split2"
        },
        {
          "cable_length": "cable_length"
        }
      ]
    ],
    "nodes": {},
    "oob": {
      "enable_dhcp": true,
      "nodes": {
        "oob-mgmt-server": {
          "cpu": 1,
          "memory": 1,
          "positioning": {
            "x": 1,
            "y": 1
          },
          "storage": 1
        },
        "oob-mgmt-switch": {
          "cpu": 1,
          "memory": 1,
          "positioning": {
            "x": 1,
            "y": 1
          },
          "storage": 1
        }
      },
      "subnets": {}
    },
    "services": [
      {
        "interface": "string",
        "name": "string",
        "node": "string",
        "node_port": 1,
        "service_type": "SSH"
      }
    ]
  },
  "format": "JSON",
  "name": "string",
  "ztp": "string"
}
```

**SDK Code**

```python
import requests

url = "https://api.dsx-air.nvidia.com/api/v3/simulations/id/export/"

querystring = {"topology_format":"JSON"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.dsx-air.nvidia.com/api/v3/simulations/id/export/?topology_format=JSON';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dsx-air.nvidia.com/api/v3/simulations/id/export/?topology_format=JSON"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.dsx-air.nvidia.com/api/v3/simulations/id/export/?topology_format=JSON")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.dsx-air.nvidia.com/api/v3/simulations/id/export/?topology_format=JSON")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.dsx-air.nvidia.com/api/v3/simulations/id/export/?topology_format=JSON', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.dsx-air.nvidia.com/api/v3/simulations/id/export/?topology_format=JSON");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.dsx-air.nvidia.com/api/v3/simulations/id/export/?topology_format=JSON")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```