> This page is for NVIDIA Infra Controller.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/infra-controller/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/infra-controller/_mcp/server.

# Retrieve Machine Spectrum-X multiplane status

GET https://nico-rest-api.nico.svc.cluster.local/v2/org/{org}/nico/machine/{machineId}/spectrumx-multiplane

Retrieve declared rail/plane configuration and separate observations for every associated BlueField-4 DPU.
An unconfigured maintenance mode or unavailable readback is null, distinct from false.
For Infrastructure Providers: Org must have an Infrastructure Provider entity and own the Site that the Machine belongs to. User must have authorization role with `PROVIDER_ADMIN` or `PROVIDER_VIEWER` suffix.

Reference: https://docs.nvidia.com/infra-controller/rest-api-reference/api-reference/machine/get-machine-spectrumx-multiplane

## Authentication

- `Authorization` header (bearer token, required) — ``` export JWT_BEARER_TOKEN="<jwt-bearer-token>" # Example org name: "acme-inc export ORG_NAME=<org-name> # Use the JWT bearer token in your API request auth header: curl -v -X GET -H "Content-Type: application/json" -H "Authorization: Bearer $JWT_BEARER_TOKEN" https://nico-rest-api.nico.svc.cluster.local/v2/org/$ORG_NAME/nico/user/current ```

## Request

### Path parameters

- `org` (string, required) — Name of the Org
- `machineId` (string, required) — ID of the Machine

## Response

### 200

Desired configuration and per-DPU observations

- `machineId` (string, required) — ID of the Machine whose maintenance configuration and DPU observations are returned.
- `interfaces` (list of MachineSpectrumXMultiplaneInterface, required) — Declared interfaces ordered by rail and plane.
- `dpuStatuses` (list of MachineSpectrumXMultiplaneDPUStatus, required) — One entry per associated BlueField-4 DPU, ordered by DPU ID. Empty when none are present.

## Errors

### 400 Bad Request Error

Error response when request data cannot be validated

- `source` (string, optional) — Source of the error, taken from `api.name` in the REST API server configuration file (`/app/config.yaml` in the supplied Kubernetes deployment; default API name `nico`). This is a configurable string, for example `nico` or `carbide`
- `message` (string, optional) — Message describing the error
- `data` (NiCoApiErrorData, optional, nullable) — Additional data about the error
- `retryable` (boolean, optional) — True permits bounded retries with backoff, without guaranteeing success. False prohibits automatic retries. Omission means unclassified.

### 403 Forbidden Error

Error response when user is not authorized to call an endpoint or retrieve/modify objects

- `source` (string, optional) — Source of the error, taken from `api.name` in the REST API server configuration file (`/app/config.yaml` in the supplied Kubernetes deployment; default API name `nico`). This is a configurable string, for example `nico` or `carbide`
- `message` (string, optional) — Message describing the error
- `data` (NiCoApiErrorData, optional, nullable) — Additional data about the error
- `retryable` (boolean, optional) — True permits bounded retries with backoff, without guaranteeing success. False prohibits automatic retries. Omission means unclassified.

### 404 Not Found Error

Error response when requested object is not found

- `source` (string, optional) — Source of the error, taken from `api.name` in the REST API server configuration file (`/app/config.yaml` in the supplied Kubernetes deployment; default API name `nico`). This is a configurable string, for example `nico` or `carbide`
- `message` (string, optional) — Message describing the error
- `data` (NiCoApiErrorData, optional, nullable) — Additional data about the error
- `retryable` (boolean, optional) — True permits bounded retries with backoff, without guaranteeing success. False prohibits automatic retries. Omission means unclassified.

### 412 Precondition Failed Error

Machine has no declared CX9 logical interfaces for multiplane maintenance

- `source` (string, optional) — Source of the error, taken from `api.name` in the REST API server configuration file (`/app/config.yaml` in the supplied Kubernetes deployment; default API name `nico`). This is a configurable string, for example `nico` or `carbide`
- `message` (string, optional) — Message describing the error
- `data` (NiCoApiErrorData, optional, nullable) — Additional data about the error
- `retryable` (boolean, optional) — True permits bounded retries with backoff, without guaranteeing success. False prohibits automatic retries. Omission means unclassified.

### 500 Internal Server Error

Response when the API handler encounters an unexpected error

- `source` (string, optional) — Source of the error, taken from `api.name` in the REST API server configuration file (`/app/config.yaml` in the supplied Kubernetes deployment; default API name `nico`). This is a configurable string, for example `nico` or `carbide`
- `message` (string, optional) — Message describing the error
- `data` (NiCoApiErrorData, optional, nullable) — Additional data about the error
- `retryable` (boolean, optional) — True permits bounded retries with backoff, without guaranteeing success. False prohibits automatic retries. Omission means unclassified.

### 503 Service Unavailable Error

Site service unavailable

- `any`

### 504 Gateway Timeout Error

Site request timed out; its outcome may still be pending

- `any`

## Types

### MachineSpectrumXMultiplaneInterface

Desired configuration for one declared rail/plane interface.

- `logicalName` (string, required) — Logical interface name in the form eth\_r\<rail>\_p\<plane>, identifying the declared rail and plane.
- `rail` (integer, required) — Rail number of this interface, from 0 through 3.
- `plane` (integer, required) — Plane number of this interface, from 0 through 7.
- `configuredMaintenanceMode` (boolean, required, nullable) — Null until an operator requests a mode. True disables links; false enables them.
- `reference` (string, required, nullable) — Reference recorded with the maintenance configuration, such as a ticket URL. Null if no reference is stored.
- `revision` (string, required) — Version of this interface's desired maintenance configuration. Compare it with each DPU observation's revision to determine whether the observation describes the current request.

### MachineSpectrumXMultiplaneDPUStatus

Independent maintenance observations from one associated BlueField-4 DPU.

- `dpuMachineId` (string, required) — ID of the associated BlueField-4 DPU whose interface observations are returned.
- `interfaces` (list of MachineSpectrumXMultiplaneObservation, required) — One entry per declared interface, including those without readback.

### NiCoApiErrorData

Additional data about the error

### MachineSpectrumXMultiplaneObservation

The last attempted interface revision and observed state. A revision may lag the desired configuration.

- `logicalName` (string, required) — Logical interface name in the form eth\_r\<rail>\_p\<plane>, matching the corresponding desired interface configuration.
- `maintenanceMode` (boolean, required, nullable) — Null when readback is unavailable; false means maintenance is off.
- `revision` (string, required) — Desired configuration revision last attempted by this DPU. May be older than the current desired revision. Empty if the DPU has not reported an observation.
- `netdev` (string, required, nullable) — Linux network device name resolved by the DPU for this logical interface. Null if no device was resolved.
- `error` (string, required, nullable) — Error from the DPU's attempt to apply or observe this interface. Null when no error has been reported.
- `observed` (datetime, required, nullable) — Timestamp when the DPU attempted to apply or observe this interface, in RFC 3339 format. Null if the DPU has not reported an observation.

## Examples

**Response**

```json
{
  "machineId": "fm100psbtmb15tgh6q5duqb8ke5grng7ksd96hetbeie9nc5pvcca6eol80",
  "interfaces": [
    {
      "logicalName": "eth_r0_p0",
      "rail": 0,
      "plane": 0,
      "configuredMaintenanceMode": false,
      "reference": "CHG-12345",
      "revision": "V1-T1748645613333257"
    }
  ],
  "dpuStatuses": []
}
```

**SDK Code**

```python
import requests

url = "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane"

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

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

print(response.json())
```

```javascript
const url = 'https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane';
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://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane"

	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://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane")

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://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane")
  .header("Authorization", "Bearer <token>")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane");
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://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/machine/machineId/spectrumx-multiplane")! 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()
```