> 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 a list of nodes.

GET http://localhost:8080/api/v1/nodes

Retrieve a list of nodes from all the Kubernetes clusters of the tenant.

Reference: https://docs.nvidia.com/run-ai/self-hosted/reference/rest-api/endpoints/organizations/nodes/get-tenant-nodes

## 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`, `status`, `nodePool`, `gpuType`, `nvLinkDomainUid`, `nvLinkCliqueId`, `clusterUuid`
- `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.
- `search` (string, optional) — Filter results by a free text search.

## Response

### 200

Executed successfully.

- `nodes` (list of Node, required)

## Errors

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

### 404 Not Found Error

The specified resource was not found

- `code` (integer, required)
- `message` (string, required)
- `details` (string, optional)

### 500 Internal Server Error

unexpected error

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

### Node

- `clusterUuid` (string, required) — The id of the cluster.
- `createdAt` (datetime, required)
- `name` (string, required) — The name of the node
- `nodePool` (string, required) — The node's NodePool.
- `status` (enum, required) — The calculated status of the node.
  - Allowed values: `Ready`, `NotReady`, `Unknown`, `MissingPrerequisites`
- `updatedAt` (datetime, required)
- `conditions` (list of NodeStatusConditionDetails, optional)
- `gpuInfo` (GpuInfo, optional)
- `id` (string, optional) — The unique identifier of the node.
- `networkTopologyLabels` (list of NetworkTopologyLabel, optional) — A list of Kubernetes node label key/value pairs that represent the node’s position in the cluster’s network topology (for example, region, zone, block, rack, or hostname). The topology is attached to the node pool on which the workload runs. The label order represents the hierarchy, from farthest (first) to closest (last). These labels are used by the NVIDIA Run:ai Scheduler when making placement decisions.
- `numa` (NumaInfo, optional) — NUMA configuration and per-NUMA-node resource data for the node.
- `nvLinkCliqueId` (string, optional, nullable) — NV Link Clique Id
- `nvLinkDomainUid` (string, optional, nullable) — NV Link Domain Uid
- `taints` (list of NodeTaint, optional)

### NodeStatusConditionDetails

- `type` (string, required) — Type of node condition.
- `reason` (string, required) — (brief) reason for the condition's last transition.
- `message` (string, optional) — Human readable message indicating details about last transition.

### GpuInfo

- `gpuType` (string, required)
- `gpuCount` (integer, required)

### NetworkTopologyLabel

- `labelKey` (string, required) — The Kubernetes node label key that identifies a topology level (for example, topology.kubernetes.io/zone or cloud.provider.com/topology-rack).
- `labelValue` (string, required) — The value of the Kubernetes node label for the specified labelKey on this node (for example, zone-a or rack-1). This value identifies the node’s placement within the corresponding topology level.

### NumaInfo

NUMA configuration and per-NUMA-node resource data for the node.

- `topologyManagerPolicy` (enum, optional) — The Kubernetes topology manager policy configured on the node, controlling how NUMA-aligned resource allocation is enforced. For more details, see [Kubernetes topology manager policies](https://kubernetes.io/docs/tasks/administer-cluster/topology-manager/#topology-manager-policies).
  - Allowed values: `none`, `best-effort`, `restricted`, `single-numa-node`

### NodeTaint

- `key` (string, required) — The taint key to be applied to a node.
- `effect` (enum, required) — The effect of the taint on pods that do not tolerate the taint.
  - Allowed values: `NoSchedule`, `PreferNoSchedule`, `NoExecute`
- `value` (string, optional) — The taint value corresponding to the taint key.

## Examples

**Response**

```json
{
  "nodes": [
    {
      "clusterUuid": "71f69d83-ba66-4822-adf5-55ce55efd210",
      "createdAt": "2024-01-15T09:30:00Z",
      "name": "worker-node-1",
      "nodePool": "node-pool-1",
      "status": "Ready",
      "updatedAt": "2024-01-15T09:30:00Z",
      "conditions": [
        {
          "type": "string",
          "reason": "KubeletNotReady",
          "message": "container runtime status check may not have completed yet"
        }
      ],
      "gpuInfo": {
        "gpuType": "Tesla-V100",
        "gpuCount": 1
      },
      "id": "string",
      "networkTopologyLabels": [
        {
          "labelKey": "string",
          "labelValue": "string"
        }
      ],
      "numa": {
        "topologyManagerPolicy": "none"
      },
      "nvLinkCliqueId": "clique-id",
      "nvLinkDomainUid": "nvlink-domain-uid",
      "taints": [
        {
          "key": "foo",
          "effect": "NoSchedule",
          "value": "bar"
        }
      ]
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "http://localhost:8080/api/v1/nodes"

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

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

print(response.json())
```

```javascript
const url = 'http://localhost:8080/api/v1/nodes';
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 := "http://localhost:8080/api/v1/nodes"

	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("http://localhost:8080/api/v1/nodes")

http = Net::HTTP.new(url.host, url.port)

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("http://localhost:8080/api/v1/nodes")
  .header("Authorization", "Bearer <token>")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'http://localhost:8080/api/v1/nodes', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("http://localhost:8080/api/v1/nodes");
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: "http://localhost:8080/api/v1/nodes")! 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()
```