> 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 Expected Rack Group GET https://nico-rest-api.nico.svc.cluster.local/v2/org/{org}/nico/expected-rack-group/{id} Retrieve a specific Expected Rack Group by its `id`. Org must have an Infrastructure Provider entity. User must have authorization role with `PROVIDER_ADMIN` or `PROVIDER_VIEWER` suffix. Alternatively, Tenant Admins with `TargetedInstanceCreation` capability can also retrieve Expected Rack Groups if they have an account with the Site's Infrastructure Provider. Reference: https://docs.nvidia.com/infra-controller/rest-api-reference/api-reference/expected-rack-group/get-expected-rack-group ## Authentication - `Authorization` header (bearer token, required) — ``` export JWT_BEARER_TOKEN="" # Example org name: "acme-inc export 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 - `id` (string, required) — ID of the Expected Rack Group ### Query parameters - `includeRelation` (enum, optional) — Related entity to expand - Allowed values: `Site` ## Response ### 200 OK - `id` (string, optional) — Unique identifier (UUID) for the Expected Rack Group - `rackGroupId` (string, optional) — Operator-supplied identifier for the rack group (opaque string; UUID syntax is not required). Unique within a Site. - `siteId` (string, optional) — ID of the Site the Expected Rack Group belongs to - `site` (Site, optional, nullable) — Site details when requested through includeRelation; otherwise null. - `topology` (string, optional) — External group-level NVLink topology identifier. - `protocol` (string, optional, nullable) — Rack fabric protocol. Null only for declarations created before protocol became required. - `racks` (list of ExpectedRackGroupRack, optional) — Ordered racks and their devices. Arrays are always present, including empty lists. Rack IDs and device identity tuples are unique across the group, with case-sensitive comparison. - `name` (string, optional) — Human-readable name of the Expected Rack Group - `description` (string, optional) — Human-readable description of the Expected Rack Group - `labels` (map from string to string, optional) — User-defined key-value pairs for organizing and categorizing Expected Rack Groups. Well-known keys (`chassis.*`, `location.*`) are used to convey chassis identity and physical location. - `created` (datetime, optional) — ISO 8601 datetime when the Expected Rack Group was created - `updated` (datetime, optional) — ISO 8601 datetime when the Expected Rack Group was last updated ## 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. ## Types ### Site Site is a datacenter that is running NVIDIA Infra Controller (NICo) services - `id` (string, optional) — Unique UUID v4 identifier for the Site in NICo Cloud - `name` (string, optional) — Name of the Site - `description` (string, optional, nullable) — Optional description for the Site - `org` (string, optional) — NGC organization ID of the Infrastructure Provider that owns the Site - `infrastructureProviderId` (string, optional) — ID of the Infrastructure Provider that owns the Site - `siteControllerVersion` (string, optional, nullable) — Version of the Site Controller software - `siteAgentVersion` (string, optional, nullable) — Version of the Site Agent software - `registrationToken` (string, optional, nullable) — Token that can be used to register a Site. Value only exposed to Provider - `registrationTokenExpiration` (datetime, optional, nullable) — Date/time when registration token expires. Value only exposed to Provider - `serialConsoleHostname` (string, optional, nullable) — Serial console hostname of the site controller - `isSerialConsoleEnabled` (boolean, optional) — Indicates if Serial Console is enabled for the Site by the Provider - `serialConsoleIdleTimeout` (integer, optional, nullable) — Maximum idle time in seconds before Serial Console is disconnected - `serialConsoleMaxSessionLength` (integer, optional, nullable) — Maximum length of Serial Console session in seconds - `isSerialConsoleSSHKeysEnabled` (boolean, optional) — Only visible to Tenant retrieving the Site. Indicates if Serial Console access using SSH Keys is enabled by Tenant - `isOnline` (boolean, optional) — Indicates if the Site is currently reachable from Cloud - `status` (enum, optional) — Status of the Site - Allowed values: `Pending`, `Registered`, `Error` - `statusHistory` (list of StatusDetail, optional) — Chronological status history for the Site - `created` (datetime, optional) — Date/time when the Site was created - `updated` (datetime, optional) — Date/time when the Site was last updated - `location` (SiteLocation, optional) — Site location information - `contact` (SiteContact, optional) — Site contact information - `capabilities` (SiteCapabilities, optional) — Site capabilities used for feature availability and configuration - `machineStats` (SiteMachineStats, optional) — Machine counts by status for the Site - `gpuStats` (list of MachineGPUStats, optional) — GPU counts grouped by GPU type for the Site. Populated when includeGpuStats is set ### ExpectedRackGroupRack One expected rack and its devices. Declaration may precede rack ingestion. Members omitted or null are treated as []; responses always return arrays. - `rackId` (string, required) — Non-blank, case-sensitive external rack identifier, unique within the group. - `members` (list of ExpectedRackGroupMember, optional, nullable) — Ordered devices in this rack. Device identities are unique across all racks in the group. ### NiCoApiErrorData Additional data about the error ### StatusDetail Describes the details of a status transition for a resource - `status` (string, optional) — State of the associated entity at a particular time - `message` (string, optional, nullable) — Description of the state and cause/remedy in case of error - `created` (datetime, optional) — Date/time when the associated entity assumed the status - `updated` (datetime, optional) — Date/time when the associated entity was last observed with this status ### SiteLocation Location of the Site - `city` (string, optional) — City where the site is located - `state` (string, optional) — State where the site is located - `country` (string, optional) — Country where the site is located ### SiteContact Contact for the Site - `email` (string, optional) — Email address of the Site contact ### SiteCapabilities Boolean flags to indicate features supported by a Site - `nativeNetworking` (boolean, optional) — Whether the Site supports native networking - `networkSecurityGroup` (boolean, optional) — Whether the Site supports Network Security Groups - `nvLinkPartition` (boolean, optional) — Whether the Site supports NVLink partitioning - `flow` (boolean, optional) — Whether the Site supports Flow-based operations - `imageBasedOperatingSystem` (boolean, optional) — Whether the Site supports image-based operating system provisioning - `vpcSlaac` (boolean, optional) — Whether the latest successfully stored Site configuration inventory reports that Core supports VPCs with SLAAC enabled. False also represents a missing Site configuration or an inventory report that omits the capability. This value is managed by Site configuration inventory and cannot be updated through the Site API. - `dpsPowerManagement` (boolean, optional, default: false) — Whether this Site accepts non-empty power resource groups and power profiles for DPS power management. When false, omission and explicit clearing remain allowed. ### SiteMachineStats Machine stats for a Site - `total` (integer, optional) — Total number of Machines at the Site - `totalByStatus` (SiteMachineStatsByStatus, optional) — Machine counts grouped by Machine status - `totalByHealth` (SiteMachineStatsByHealth, optional) — Machine counts grouped by health state - `totalByStatusAndHealth` (SiteMachineStatsByStatusAndHealth, optional) — Machine health counts grouped by Machine status - `totalByAllocation` (SiteMachineStatsByAllocation, optional) — Machine counts grouped by allocation and usage state ### MachineGPUStats GPU summary stats for a single GPU type across machines at a site - `name` (string, optional) — GPU name from the MachineCapability record - `gpus` (integer, optional) — Total number of GPUs (summation of all Machine GPU capability counts) - `machines` (integer, optional) — Number of machines that have this GPU capability ### ExpectedRackGroupMember External device identity; the case-sensitive tuple (type, manufacturer, id) is unique within a group. - `type` (enum, required) — Case-sensitive REST rack component type. NVSwitch maps to Switch in Core. - Allowed values: `Compute`, `NVSwitch`, `PowerShelf` - `manufacturer` (string, required) — Non-blank manufacturer name. - `id` (string, required) — Non-blank opaque external device inventory identifier. ### SiteMachineStatsByStatus Machine stats for a Site by status - `Decommissioned` (integer, optional) — Number of Machines in Decommissioned status - `Decommissioning` (integer, optional) — Number of Machines in Decommissioning status - `Error` (integer, optional) — Number of Machines in Error status - `Initializing` (integer, optional) — Number of Machines in Initializing status - `InUse` (integer, optional) — Number of Machines in InUse status - `Maintenance` (integer, optional) — Number of Machines in Maintenance status - `Ready` (integer, optional) — Number of Machines in Ready status - `Reset` (integer, optional) — Number of Machines in Reset status - `Unknown` (integer, optional) — Number of Machines in Unknown status ### SiteMachineStatsByHealth Machine stats for a Site by health - `healthy` (integer, optional) — Number of healthy Machines - `unhealthy` (integer, optional) — Number of unhealthy Machines ### SiteMachineStatsByStatusAndHealth Machine stats for a Site by status and health - `Decommissioned` (SiteMachineStatsByHealth, optional) — Health breakdown for Machines in Decommissioned status - `Decommissioning` (SiteMachineStatsByHealth, optional) — Health breakdown for Machines in Decommissioning status - `Error` (SiteMachineStatsByHealth, optional) — Health breakdown for Machines in Error status - `Initializing` (SiteMachineStatsByHealth, optional) — Health breakdown for Machines in Initializing status - `InUse` (SiteMachineStatsByHealth, optional) — Health breakdown for Machines in InUse status - `Maintenance` (SiteMachineStatsByHealth, optional) — Health breakdown for Machines in Maintenance status - `Ready` (SiteMachineStatsByHealth, optional) — Health breakdown for Machines in Ready status - `Reset` (SiteMachineStatsByHealth, optional) — Health breakdown for Machines in Reset status - `Unknown` (SiteMachineStatsByHealth, optional) — Health breakdown for Machines in Unknown status ### SiteMachineStatsByAllocation Machine stats for a Site by allocation - `allocatedInUse` (integer, optional) — Number of allocated Machines currently in use - `allocatedNotInUse` (integer, optional) — Number of allocated Machines not currently in use - `unallocated` (integer, optional) — Number of Machines not currently allocated ## Examples **Response** ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "rackGroupId": "nvl5-gp1-jhb01", "siteId": "f97df110-f4de-492e-8849-4a6af68026b0", "topology": "gb200_nvl72r1_c2g4", "protocol": "NVLINK_V6", "racks": [ { "rackId": "rack-01", "members": [ { "type": "NVSwitch", "manufacturer": "NVIDIA", "id": "switch-01" } ] }, { "rackId": "rack-02", "members": [] } ], "name": "NVL rack group 1", "description": "Production NVL rack group in row A", "labels": { "chassis.manufacturer": "NVIDIA", "chassis.model": "GB200-NVL72", "chassis.serial-number": "NVRK0001001", "location.datacenter": "phx-dc01", "location.position": "A1", "location.region": "us-west-2", "location.room": "room-1" }, "created": "2019-08-24T14:15:22Z", "updated": "2019-08-24T14:15:22Z" } ``` **SDK Code** ```python import requests url = "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/expected-rack-group/id" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/expected-rack-group/id'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; 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/expected-rack-group/id" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") 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/expected-rack-group/id") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/expected-rack-group/id") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/expected-rack-group/id', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/expected-rack-group/id"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/expected-rack-group/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() ```