> This page is for Self-Hosted, version v3.0 (default). > For other versions, use one of these documentation indexes: > - v3.0 (default): https://docs.nvidia.com/run-ai/self-hosted/v3.0/llms.txt > - v2.26: https://docs.nvidia.com/run-ai/self-hosted/v2.26/llms.txt > - v2.25: https://docs.nvidia.com/run-ai/self-hosted/v2.25/llms.txt > - v2.24: https://docs.nvidia.com/run-ai/self-hosted/v2.24/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/run-ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/run-ai/_mcp/server. # Get nodepools GET http://localhost:8080/api/v1/node-pools Get nodepools Reference: https://docs.nvidia.com/run-ai/self-hosted/reference/rest-api/endpoints/organizations/node-pools/get-nodepools ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication ## Request ### Query parameters - `filterBy` (list of string, optional) — Filter results by a parameter. Use the format field-name operator value. Operators are == Equals, != Not equals, \<= Less than or equal, >= Greater than or equal, =@ contains, !@ Does not contains, =^ Starts with and =\$ Ends with. Dates are in ISO 8601 timestamp format and available for operators ==, !=, \<= and >=. - `sortBy` (enum, optional) — Sort results by a parameters. - Allowed values: `name`, `phase`, `clusterId`, `createdAt`, `updatedAt`, `networkTopologyName`, `gpuNetworkAccelerationDetection`, `gpuNetworkAccelerationDetected`, `gpuNetworkAccelerationLabelKey` - `sortOrder` (enum, optional, default: asc) — Sort results in descending or ascending order. - Allowed values: `asc`, `desc` - `offset` (integer, optional) — The offset of the first item returned in the collection. - `limit` (integer, optional, default: 50) — The maximum number of entries to return. ## Response ### 200 ok - `nodepools` (list of Nodepool, optional) ## Errors ### 400 Bad Request Error Bad request. - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ### 401 Unauthorized Error Unauthorized - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ### 403 Forbidden Error Forbidden - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ### 503 Service Unavailable Error unexpected error - `code` (integer, required) - `message` (string, required) - `details` (string, optional) ## Types ### Nodepool - `name` (string, required) - `labelKey` (string, required) — Label key for associated nodes to the Node Pool (with value as in labelValue) - `labelValue` (string, required) — Label value for associated nodes to the Node Pool (with key as in labelKey) - `clusterId` (string, required) - `id` (string, required) — The NodePool id - `tenantId` (integer, required) — The id of the tenant. - `clusterName` (string, required) - `createdBy` (string, required) - `createdAt` (datetime, required) - `updatedBy` (string, required) - `updatedAt` (datetime, required) - `isDefault` (boolean, required) — Is the Node Pool is the cluster default - `gpuNetworkAccelerationLabelKey` (string, optional) — Label key by which to determine GPUNetworkAccelerationDetection nodes - `gpuNetworkAccelerationDetection` (enum, optional, default: Auto) — GPUNetworkAccelerationDetection is a strategy to use for GPU Network Acceleration detection - Allowed values: `Use`, `DontUse`, `Auto` - `networkTopologyName` (string, optional) — Name of the network topology - `networkTopologyId` (string, optional) — The unique identifier for the network topology - `schedulingConfiguration` (SchedulingConfiguration, optional) - `phase` (enum, optional) — Phase of Node Pool - Allowed values: `Creating`, `Updating`, `Deleting`, `Empty`, `Unschedulable`, `MissingPrerequisites`, `Ready`, `Deleted` - `phaseMessage` (string, optional) — Message for status of Node Pool - `status` (NodepoolStatus, optional) - `deletedBy` (string, optional) - `deletedAt` (datetime, optional, nullable) ### SchedulingConfiguration - `gpuPodsPlacementStrategy` (GpuPodsPlacementStrategy, optional) — Defines the placement strategy for GPU pods within the node pool. - `cpuPodsPlacementStrategy` (CpuPodsPlacementStrategy, optional) — Defines the placement strategy for CPU pods within the node pool. - `minGuaranteedRuntime` (string, optional, nullable) — Minimum duration (e.g., 5d8h40m) that a preemptible workload is guaranteed to run once scheduled and bound to a node. During this period, it is considered non-preemptible even if a higher-priority workload becomes eligible. Defaults to 0 (immediate preemption allowed). - `timeBasedFairShare` (TimeBasedFairShare, optional) — Time-based fairshare configuration for the node pool. [Experimental]. - `numaAwareScheduling` (boolean, optional, nullable) — When enabled, the Scheduler places workloads so that GPU, CPU, and CPU memory are allocated within the same NUMA node where possible, minimizing cross-NUMA fragmentation and improving performance. Requires the NodeResourceTopology (NRT) component and a Topology Manager policy other than 'none' on the pool's nodes. When disabled, the Scheduler places workloads using aggregate node capacity only, without considering NUMA topology. - `placementStrategy` (SchedulingConfigurationPlacementStrategy, optional, deprecated) — Deprecated. Use gpuPodsPlacementStrategy and cpuPodsPlacementStrategy instead. On write, when a new field is provided it takes precedence over the equivalent field here. On read, both this field and the new fields are returned; this field reflects the node-level strategies. ### NodepoolStatus - `labelKey` (string, optional, nullable) — Label key for associated nodes to the Node Pool (with value as in labelValue) - `labelValue` (string, optional, nullable) — Label value for associated nodes to the Node Pool (with key as in labelKey) - `gpuNetworkAccelerationLabelKey` (string, optional) — Label key by which to determine GPUNetworkAccelerationDetection nodes - `gpuNetworkAccelerationDetection` (enum, optional, default: Auto) — GPUNetworkAccelerationDetection is a strategy to use for GPU Network Acceleration detection - Allowed values: `Use`, `DontUse`, `Auto` - `gpuResourceOptimization` (GPUResourceOptimization, optional) - `schedulingConfiguration` (SchedulingConfiguration, optional) - `conditions` (list of NodepoolConditionDetails, optional) - `gpuNetworkAccelerationDetected` (boolean, optional) — Signals to all relevant parties about GPUNetworkAcceleration being detected in some nodepool's nodes - `nodes` (list of string, optional) - `placementStrategy` (NodepoolStatusPlacementStrategy, optional, deprecated) — scheduling strategy per resource - `overProvisioningRatio` (integer, optional, nullable, deprecated) ### GpuPodsPlacementStrategy Defines the placement strategy for GPU pods within the node pool. - `node` (enum, optional) — Specifies how GPU pods are placed across nodes. - binpack - Place as many GPU pods as possible on each node to use fewer nodes and maximize available capacity. - spread - Distribute GPU pods across as many nodes as possible to balance load across nodes. - Allowed values: `spread`, `binpack` - `device` (enum, optional) — Specifies how GPU pods are placed across GPU devices within a node when using GPU fractions. - binpack - Place as many GPU pods as possible on each GPU device to use fewer devices and maximize available capacity, minimizing GPU fraction fragmentation. - spread - Distribute GPU pods across as many GPU devices as possible to balance load across devices. - Allowed values: `spread`, `binpack` ### CpuPodsPlacementStrategy Defines the placement strategy for CPU pods within the node pool. - `node` (enum, optional) — Specifies how CPU pods are placed across nodes. - binpack - Place as many CPU pods as possible on each node to use fewer nodes and maximize available capacity. - spread - Distribute CPU pods across as many nodes as possible to balance load across nodes. - Allowed values: `spread`, `binpack` ### TimeBasedFairShare Time-based fairshare configuration for the node pool. [Experimental]. - `enabled` (boolean, optional, nullable, default: false) — Enables time-based fairshare for the node pool. When true, the Scheduler adjusts fairshare based on historical resource usage over a defined time window, allowing past consumption to influence scheduling order. When false, scheduling is based only on the current queue state. [Experimental] - `historicalUsageWeight` (float, optional, nullable, default: 1) — Set the weight value that determines how a project’s historical resource usage affects its fairshare. - 0.0: Ignore historical usage data (100% current usage). - 1.0: Historical usage data has higher impact, it may cause fairshare to be 0. - Values between 0.0 and 1.0 combine historical and current usage to maintain a balanced fairshare - Values above 1 will cause historical usage to have an even higher impact on fairshare. - `decayHalfLife` (string, optional, nullable, default: 0h) — Set the half-life time to define the decay rate of a project’s historical resource usage. The half-life defines how long it takes for past usage to diminish to half of its original influence on a project's fairshare. - 0: disables decay; all historical usage is weighted equally. - > 0: older usage gradually contributes less over time (e.g., with a 24-hour half-life, usage from 24 hours ago contributes 50%, from 48 hours ago 25%, and so on). - `windowType` (enum, optional, default: sliding) — The method for evaluating the usage window. - sliding: A moving window that always evaluates the most recent time period. For example, a 7-day sliding window always considers the last 7 days. - tumbling: Fixed, non-overlapping intervals that reset at the end of each cycle. Requires tumblingWindowStartTime to define the cycle anchor. - Allowed values: `sliding`, `tumbling` - `windowDuration` (string, optional, nullable, default: 7d) — The time period over which historical usage is evaluated. Only usage within this window contributes to fairshare. For sliding windows, this is a moving period (e.g., 7d = always the last 7 days). For tumbling windows, this is the fixed cycle duration after which the window resets. - `tumblingWindowStartTime` (datetime, optional, nullable) — An RFC-3339 timestamp that defines the start time for all tumbling windows. Used only when windowType = Tumbling. This timestamp marks the beginning of the first fixed window, and subsequent windows repeat at intervals equal to the configured WindowDuration. For example, with a 7-day window, an anchor of 2025-01-06T08:00:00Z produces weekly windows starting every Monday at 08:00 UTC. ### SchedulingConfigurationPlacementStrategy Deprecated. Use gpuPodsPlacementStrategy and cpuPodsPlacementStrategy instead. On write, when a new field is provided it takes precedence over the equivalent field here. On read, both this field and the new fields are returned; this field reflects the node-level strategies. - `cpu` (enum, optional) - Allowed values: `spread`, `binpack` - `gpu` (enum, optional) - Allowed values: `spread`, `binpack` ### GPUResourceOptimization - `swapEnabled` (boolean, optional, nullable, default: false, deprecated) — Indicates if swap is enabled on the node pool - `cpuSwapMemorySize` (string, optional, nullable, default: 100G, deprecated) — Size of the swap cpu memory. Only allowed when swapEnabled is true - `reservedGpuMemoryForSwapOperations` (string, optional, nullable, default: 2G, deprecated) — Reserved GPU memory for swap operations. Only allowed when swapEnabled is true - `nodeLevelSchedulerEnabled` (boolean, optional, nullable, default: false, deprecated) — Indicates if node level scheduler is enabled on the node pool ### NodepoolConditionDetails - `type` (string, required) — Type of Nodepool condition. - `reason` (string, required) — (brief) reason for the condition's last transition. - `message` (string, optional) — Human readable message indicating details about last transition. - `status` (enum, optional) — The status of the condition, can be True or False - Allowed values: `True`, `False` - `nodes` (list of string, optional) — Names of the nodes related to the nodepool condition ### NodepoolStatusPlacementStrategy scheduling strategy per resource - `cpu` (enum, optional) - Allowed values: `spread`, `binpack` - `gpu` (enum, optional) - Allowed values: `spread`, `binpack` ## Examples **Response** ```json { "nodepools": [ { "name": "v100", "labelKey": "node-type", "labelValue": "type-x", "clusterId": "d73a738f-fab3-430a-8fa3-5241493d7128", "id": "5", "tenantId": 1, "clusterName": "prod-cluster", "createdBy": "user@lab.com", "createdAt": "2024-01-15T09:30:00Z", "updatedBy": "user@lab.com", "updatedAt": "2024-01-15T09:30:00Z", "isDefault": false, "gpuNetworkAccelerationLabelKey": "string", "gpuNetworkAccelerationDetection": "Auto", "networkTopologyName": "default-topology", "networkTopologyId": "123e4567-e89b-12d3-a456-426614174000", "schedulingConfiguration": { "gpuPodsPlacementStrategy": { "node": "spread", "device": "spread" }, "cpuPodsPlacementStrategy": { "node": "spread" }, "minGuaranteedRuntime": "5d8h40m", "timeBasedFairShare": { "enabled": true, "historicalUsageWeight": 1.5, "decayHalfLife": "24h", "windowType": "tumbling", "windowDuration": "2d", "tumblingWindowStartTime": "2025-01-06T08:00:00Z" }, "numaAwareScheduling": true, "placementStrategy": { "cpu": "spread", "gpu": "spread" } }, "phase": "Creating", "phaseMessage": "all nodes are down", "status": { "labelKey": "node-type", "labelValue": "type-x", "gpuNetworkAccelerationLabelKey": "string", "gpuNetworkAccelerationDetection": "Auto", "gpuResourceOptimization": { "swapEnabled": true, "cpuSwapMemorySize": "10000M", "reservedGpuMemoryForSwapOperations": "10G", "nodeLevelSchedulerEnabled": true }, "schedulingConfiguration": { "gpuPodsPlacementStrategy": { "node": "spread", "device": "spread" }, "cpuPodsPlacementStrategy": { "node": "spread" }, "minGuaranteedRuntime": "5d8h40m", "timeBasedFairShare": { "enabled": true, "historicalUsageWeight": 1.5, "decayHalfLife": "24h", "windowType": "tumbling", "windowDuration": "2d", "tumblingWindowStartTime": "2025-01-06T08:00:00Z" }, "numaAwareScheduling": true, "placementStrategy": { "cpu": "spread", "gpu": "spread" } }, "conditions": [ { "type": "string", "reason": "TopologyMismatch", "message": "Network Topology labels mismatch", "status": "True", "nodes": [ "node1", "node2" ] } ], "gpuNetworkAccelerationDetected": true, "nodes": [ "node1" ], "placementStrategy": { "cpu": "spread", "gpu": "spread" }, "overProvisioningRatio": 1 }, "deletedBy": "user@lab.com", "deletedAt": "2024-01-15T09:30:00Z" } ] } ``` **SDK Code** ```python import requests url = "http://localhost:8080/api/v1/node-pools" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'http://localhost:8080/api/v1/node-pools'; 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 := "http://localhost:8080/api/v1/node-pools" 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("http://localhost:8080/api/v1/node-pools") http = Net::HTTP.new(url.host, url.port) 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("http://localhost:8080/api/v1/node-pools") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'http://localhost:8080/api/v1/node-pools', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("http://localhost:8080/api/v1/node-pools"); 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: "http://localhost:8080/api/v1/node-pools")! 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() ```