> 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 all Expected Rack Groups GET https://nico-rest-api.nico.svc.cluster.local/v2/org/{org}/nico/expected-rack-group Retrieve all Expected Rack Groups. 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 (siteId query parameter is required for Tenants). Reference: https://docs.nvidia.com/infra-controller/rest-api-reference/api-reference/expected-rack-group/get-all-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 ### Query parameters - `siteId` (string, optional) — ID of the Site to filter Expected Rack Groups by - `includeRelation` (enum, optional) — Related entity to expand - Allowed values: `Site` - `pageNumber` (integer, optional) — Page number for pagination query - `pageSize` (integer, optional) — Page size for pagination query - `orderBy` (enum, optional, default: CREATED_ASC) — Ordering for pagination query. Defaults to `CREATED_ASC`, with ID ascending as the tie-breaker. - Allowed values: `RACK_GROUP_ID_ASC`, `RACK_GROUP_ID_DESC`, `ID_ASC`, `ID_DESC`, `SITE_ID_ASC`, `SITE_ID_DESC`, `NAME_ASC`, `NAME_DESC`, `TOPOLOGY_ASC`, `TOPOLOGY_DESC`, `CREATED_ASC`, `CREATED_DESC`, `UPDATED_ASC`, `UPDATED_DESC` ## Response ### 200 OK - `list of ExpectedRackGroup` ## 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. ## Types ### ExpectedRackGroup An Expected Rack Group declares a group-level NVLink topology, racks, and expected device members. The `rackGroupId` is an operator-supplied string identifier (UUID syntax is not required) that uniquely identifies the group within the Site. Topology is supplied by the external inventory system. Chassis identity and physical location information are conveyed via well-known label keys in `labels`: - `chassis.manufacturer`, `chassis.serial-number`, `chassis.model` - `location.region`, `location.datacenter`, `location.room`, `location.position` - `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 ### NiCoApiErrorData Additional data about the error ### 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. ### 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 **Request** ```json {} ``` **Response** ```json [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "rackGroupId": "nvl5-gp1-jhb01", "siteId": "f97df110-f4de-492e-8849-4a6af68026b0", "site": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "San Jose Central 4", "description": "Datacenter serving the San Jose central region", "org": "qygdmg8oqik8", "infrastructureProviderId": "5f2cc306-76e9-4fca-9186-950c9ef9a74e", "siteControllerVersion": "0.1", "siteAgentVersion": "0.1", "registrationToken": "J7KO-89RR-Y7WQ-AD90", "registrationTokenExpiration": "2019-08-25T12:00:00Z", "serialConsoleHostname": "sjc.nico.acme.com", "isSerialConsoleEnabled": true, "serialConsoleIdleTimeout": 60, "serialConsoleMaxSessionLength": 3600, "isSerialConsoleSSHKeysEnabled": true, "isOnline": false, "status": "Pending", "statusHistory": [ { "status": "Pending", "message": "Request received, pending processing", "created": "2019-08-24T14:15:22Z", "updated": "2019-08-24T14:15:22Z" } ], "created": "2019-08-24T14:15:22Z", "updated": "2019-08-24T14:15:22Z", "location": { "city": "San Jose", "state": "CA", "country": "USA" }, "contact": { "email": "johndoe@nvidia.com" }, "capabilities": { "nativeNetworking": true, "networkSecurityGroup": true, "nvLinkPartition": false, "flow": true, "imageBasedOperatingSystem": false, "vpcSlaac": false, "dpsPowerManagement": false }, "machineStats": { "total": 15, "totalByStatus": { "Decommissioned": 0, "Decommissioning": 0, "Error": 5, "Initializing": 0, "InUse": 3, "Maintenance": 0, "Ready": 7, "Reset": 0, "Unknown": 0 }, "totalByHealth": { "healthy": 12, "unhealthy": 3 }, "totalByStatusAndHealth": { "Decommissioned": { "healthy": 0, "unhealthy": 0 }, "Decommissioning": { "healthy": 0, "unhealthy": 0 }, "Error": { "healthy": 2, "unhealthy": 3 }, "Initializing": { "healthy": 0, "unhealthy": 0 }, "InUse": { "healthy": 3, "unhealthy": 0 }, "Maintenance": { "healthy": 5, "unhealthy": 0 }, "Ready": { "healthy": 5, "unhealthy": 0 }, "Reset": { "healthy": 0, "unhealthy": 0 }, "Unknown": { "healthy": 0, "unhealthy": 0 } }, "totalByAllocation": { "allocatedInUse": 3, "allocatedNotInUse": 3, "unallocated": 5 } }, "gpuStats": [ { "name": "NVIDIA GB200", "gpus": 64, "machines": 16 } ] }, "topology": "gb200_nvl72r1_c2g4", "protocol": "NVLINK_V6", "racks": [ { "rackId": "rack-01", "members": [ { "type": "NVSwitch", "manufacturer": "NVIDIA", "id": "switch-01" }, { "type": "Compute", "manufacturer": "NVIDIA", "id": "compute-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": "2024-01-15T09:30:00Z", "updated": "2024-01-15T09:30:00Z" } ] ``` **SDK Code** ```python import requests url = "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/expected-rack-group" querystring = {"pageSize":"20"} payload = {} headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.get(url, json=payload, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/expected-rack-group?pageSize=20'; const options = { method: 'GET', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{}' }; 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" "strings" "net/http" "io" ) func main() { url := "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/expected-rack-group?pageSize=20" payload := strings.NewReader("{}") req, _ := http.NewRequest("GET", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") 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?pageSize=20") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{}" 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?pageSize=20") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{}") .asString(); ``` ```php request('GET', 'https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/expected-rack-group?pageSize=20', [ 'body' => '{}', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); 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?pageSize=20"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/expected-rack-group?pageSize=20")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers request.httpBody = postData as Data 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() ```