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

# Get an instruction

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

Returns one instruction: the `node` it targets, its `data` (the commands to run, the files to write or the hostname to set), and its `state`. Instructions that Air creates itself, such as the hostname setup of each node, are returned as well.

Use this operation to follow an instruction after you create it. The worker has run the instruction when `state` is `COMPLETE` or `FAILED`. `CANCELLED` means that the instruction was cancelled before it ran.

**Required scope:** Simulation Read (roles: Air Org Administrator, Air User)

**Alternative:** the Air Trainee role also grants access.

Reference: https://docs.nvidia.com/dsx-air/api-reference/instructions/api-v-3-simulations-devices-instructions-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 instruction.

## Response

### 200

- `InstructionReadSerializerTypes`
  - InitInstructionRead: InitInstructionRead
  - FileInstructionRead: FileInstructionRead
  - ShellInstructionRead: ShellInstructionRead

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

## Types

### InitInstructionRead

Representation of a hostname assignment instruction.

- `id` (string, required)
- `created` (datetime, required)
- `modified` (datetime, required)
- `node` (string, required) — The node which will execute the instruction.
- `device` (string, required, nullable) — The `id` of the device this instruction runs on, when its node is one a device runs (e.g. a DPU). `null` for a standalone node.
- `data` (InitDataRead, required) — Data on what hostname should be assigned to the node when it initializes.
- `state` (enum, required) — The current lifecycle state of this instruction. Defaults to NOT_READY; transitions to READY once the target VM is running. * `NOT_READY` - The instruction exists but is not yet ready for worker pickup. * `READY` - The instruction is ready to be picked up and executed. * `IN_PROGRESS` - The instruction has been picked up by the worker. * `COMPLETE` - The instruction was successfully executed. * `FAILED` - The instruction failed to finish execution. * `CANCELLED` - The instruction was cancelled before execution.
  - Allowed values: `NOT_READY`, `READY`, `IN_PROGRESS`, `COMPLETE`, `FAILED`, `CANCELLED`
- `created_by_client` (boolean, required) — Whether the instruction was created by a client.
- `wait_for_network` (boolean, required) — Whether to wait for network connectivity before executing the instruction.
- `reachability_check` (any, required, nullable) — Configuration for network reachability check. None when wait_for_network is False or not set.
- `name` (string, optional) — The name of the instruction.
- `run_again_on_rebuild` (boolean, optional) — If the instruction should be run again if the simulation is rebuilt.

### FileInstructionRead

Representation of an instruction that writes files to a node.

- `id` (string, required)
- `created` (datetime, required)
- `modified` (datetime, required)
- `node` (string, required) — The node which will execute the instruction.
- `device` (string, required, nullable) — The `id` of the device this instruction runs on, when its node is one a device runs (e.g. a DPU). `null` for a standalone node.
- `data` (FileDataRead, required) — Information needed to write files to the node.
- `state` (enum, required) — The current lifecycle state of this instruction. Defaults to NOT_READY; transitions to READY once the target VM is running. * `NOT_READY` - The instruction exists but is not yet ready for worker pickup. * `READY` - The instruction is ready to be picked up and executed. * `IN_PROGRESS` - The instruction has been picked up by the worker. * `COMPLETE` - The instruction was successfully executed. * `FAILED` - The instruction failed to finish execution. * `CANCELLED` - The instruction was cancelled before execution.
  - Allowed values: `NOT_READY`, `READY`, `IN_PROGRESS`, `COMPLETE`, `FAILED`, `CANCELLED`
- `created_by_client` (boolean, required) — Whether the instruction was created by a client.
- `wait_for_network` (boolean, required) — Whether to wait for network connectivity before executing the instruction.
- `reachability_check` (any, required, nullable) — Configuration for network reachability check. None when wait_for_network is False or not set.
- `name` (string, optional) — The name of the instruction.
- `run_again_on_rebuild` (boolean, optional) — If the instruction should be run again if the simulation is rebuilt.

### ShellInstructionRead

Representation of an arbitrary shell execution instruction.

- `id` (string, required)
- `created` (datetime, required)
- `modified` (datetime, required)
- `node` (string, required) — The node which will execute the instruction.
- `device` (string, required, nullable) — The `id` of the device this instruction runs on, when its node is one a device runs (e.g. a DPU). `null` for a standalone node.
- `data` (ShellDataRead, required) — Information on shell commands to be run on the node.
- `state` (enum, required) — The current lifecycle state of this instruction. Defaults to NOT_READY; transitions to READY once the target VM is running. * `NOT_READY` - The instruction exists but is not yet ready for worker pickup. * `READY` - The instruction is ready to be picked up and executed. * `IN_PROGRESS` - The instruction has been picked up by the worker. * `COMPLETE` - The instruction was successfully executed. * `FAILED` - The instruction failed to finish execution. * `CANCELLED` - The instruction was cancelled before execution.
  - Allowed values: `NOT_READY`, `READY`, `IN_PROGRESS`, `COMPLETE`, `FAILED`, `CANCELLED`
- `created_by_client` (boolean, required) — Whether the instruction was created by a client.
- `wait_for_network` (boolean, required) — Whether to wait for network connectivity before executing the instruction.
- `reachability_check` (any, required, nullable) — Configuration for network reachability check. None when wait_for_network is False or not set.
- `name` (string, optional) — The name of the instruction.
- `run_again_on_rebuild` (boolean, optional) — If the instruction should be run again if the simulation is rebuilt.

### InitDataRead

Data on what hostname should be assigned to the node when it initializes.

- `executor` (enum, required) — The `init` executor option. * `init` - init
  - Allowed values: `init`
- `hostname` (string, required) — Hostname to assign to the node when it initializes.

### FileDataRead

Information needed to write files to the node.

- `executor` (enum, required) — The `file` executor option. * `file` - file
  - Allowed values: `file`
- `files` (list of NestedFileInfo, 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.

### ShellDataRead

Information on shell commands to be run on the node.

- `executor` (enum, required) — The `shell` executor option. * `shell` - shell
  - Allowed values: `shell`
- `commands` (list of string, required) — List of shell commands to run on the node, in order.

### NestedFileInfo

Information about an individual file to be written to the node.

- `path` (string, required) — Path on the node where the file will be written.
- `content` (string, required) — Text content to write into the file.

## Examples

**Response**

```json
{
  "created": "2024-01-15T09:30:00Z",
  "created_by_client": true,
  "data": {
    "executor": "init",
    "hostname": "string"
  },
  "device": "string",
  "id": "string",
  "modified": "2024-01-15T09:30:00Z",
  "name": "string",
  "node": "string",
  "reachability_check": null,
  "run_again_on_rebuild": true,
  "state": "NOT_READY",
  "wait_for_network": true
}
```

**SDK Code**

```python
import requests

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

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

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

print(response.json())
```

```javascript
const url = 'https://api.dsx-air.nvidia.com/api/v3/simulations/devices/instructions/id/';
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/devices/instructions/id/"

	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/devices/instructions/id/")

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/devices/instructions/id/")
  .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/devices/instructions/id/', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.dsx-air.nvidia.com/api/v3/simulations/devices/instructions/id/");
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/devices/instructions/id/")! 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()
```