> 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 cluster by id.

GET http://localhost:8080/api/v1/clusters/{clusterUuid}

Retrieve cluster details by Universally Unique Identifier (UUID).

Reference: https://docs.nvidia.com/run-ai/self-hosted/reference/rest-api/endpoints/organizations/clusters/get-cluster-by-uuid

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication

## Request

### Path parameters

- `clusterUuid` (string, required) — The Universally Unique Identifier (UUID) of the cluster.

### Query parameters

- `verbosity` (enum, optional, default: full) — response verbosity level.
  - Allowed values: `metadata`, `full`

## Response

### 200

Executed successfully.

- `uuid` (string, required)
- `tenantId` (integer, required) — The id of the tenant.
- `name` (string, required)
- `createdAt` (datetime, required)
- `domain` (string, optional, nullable)
- `version` (string, optional, nullable)
- `status` (ClusterDisplayedStatus, optional) — The cluster's displayed status.
- `updatedAt` (datetime, optional, nullable)
- `deletedAt` (datetime, optional, nullable)
- `lastLiveness` (datetime, optional, nullable)
- `deleteRequestedAt` (datetime, optional, nullable) — the timestamp value of when the cluster deletion request was received

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

### ClusterDisplayedStatus

The cluster's displayed status.

- `conditions` (list of ClusterReportedStatusConditionsItems, optional)
- `config` (ClusterReportedConfig, optional) — Holds cluster configuration values.
- `dependencies` (ClusterDependenciesStatus, optional)
- `operands` (map from string to ClusterReportedStatusOperands, optional) — OperandStatuses specifies the status of the managed operands
- `platform` (ClusterReportedStatusPlatform, optional)
- `state` (enum, optional) — The cluster's state.
  - Allowed values: `WaitingToConnect`, `Connected`, `Disconnected`, `MissingPrerequisites`, `ServiceIssues`, `Unknown`

### ClusterReportedStatusConditionsItems

Condition contains details for one aspect of the current state of this API Resource

- `lastTransitionTime` (datetime, required) — lastTransitionTime is the last time the condition transitioned from one status to another. This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.
- `message` (string, required) — message is a human readable message indicating details about the transition. This may be an empty string.
- `reason` (string, required) — reason contains a programmatic identifier indicating the reason for the condition's last transition. Producers of specific condition types may define expected values and meanings for this field, and whether the values are considered a guaranteed API. The value should be a CamelCase string. This field may not be empty.
- `status` (enum, required) — status of the condition, one of True, False, Unknown.
  - Allowed values: `True`, `False`, `Unknown`
- `type` (string, required) — type of condition in CamelCase or in foo.example.com/CamelCase. --- Many .condition.type values are consistent across resources like Available, but because arbitrary conditions can be useful (see .node.status.conditions), the ability to deconflict is important. The regex it matches is (dns1123SubdomainFmt/)?(qualifiedNameFmt)
- `observedGeneration` (long, optional) — observedGeneration represents the .metadata.generation that the condition was set based upon. For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date with respect to the current state of the instance.

### ClusterReportedConfig

Holds cluster configuration values.

- `workloadOwnershipProtection` (boolean, optional, nullable) — indicates if the cluster workload ownership protection is enabled
- `subdomainEnabled` (boolean, optional, nullable) — indicates if the cluster subdomain is enabled
- `ingressClass` (string, optional, nullable) — the ingress class that is configured for the cluster
- `ingressEnabled` (boolean, optional, nullable) — indicates if Ingress or Route resources should be created for workload external URLs
- `gatewayName` (string, optional, nullable) — the name of the Gateway API gateway resource configured for the cluster
- `gatewayNamespace` (string, optional, nullable) — the namespace of the Gateway API gateway resource configured for the cluster
- `gatewayAPIEnabled` (boolean, optional, nullable) — indicates if Gateway API HTTPRoute resources should be created for workload external URLs
- `gitSyncImage` (string, optional, nullable) — the fully qualified git-sync image reference used by init containers (format "registry/name:tag")
- `gitSyncResources` (ClusterReportedResourceRequirements, optional) — Resource requests and limits reported by a cluster for a composed container.
- `s3FileSystemImage` (string, optional, nullable) — the fully qualified s3 file-system image reference used by init containers (format "registry/name:tag")
- `s3FileSystemResources` (ClusterReportedResourceRequirements, optional) — Resource requests and limits reported by a cluster for a composed container.
- `fipsMode` (enum, optional) — the cluster's Go FIPS 140-3 runtime mode (off, on, or only), propagated to injected init/sidecar containers via GODEBUG
  - Allowed values: `off`, `on`, `only`
- `runaiOauth2ProxyImage` (string, optional, nullable) — the fully qualified runai oauth2-proxy image reference used by init containers (format "registry/name:tag")
- `runaiOauth2ProxyResources` (ClusterReportedResourceRequirements, optional) — Resource requests and limits reported by a cluster for a composed container.
- `runaiOauth2ProxyUsernameLoaderImage` (string, optional, nullable) — the fully qualified runai oauth2-proxy username loader image reference used by init containers (format "registry/name:tag")
- `usernameLoaderResources` (ClusterReportedResourceRequirements, optional) — Resource requests and limits reported by a cluster for a composed container.
- `runaiOauth2ProxyRedisFQDN` (string, optional, nullable) — the FQDN of the Redis backing oauth2-proxy
- `runaiOauth2ProxyWorkloadAuthSecretName` (string, optional, nullable) — the name of the Secret holding the oauth2-proxy workload auth credentials
- `runaiOauth2ProxySessionStoreType` (string, optional, nullable) — the session store type used by oauth2-proxy
- `runaiOauth2ProxyOidcIssuerUrl` (string, optional, nullable) — the absolute OIDC issuer URL oauth2-proxy uses to discover the OpenID provider
- `customCAGit` (ClusterReportedCustomCA, optional) — Custom CA bundle reported by the cluster for a specific consumer (git-sync, S3, oauth2-proxy).
- `customCAS3` (ClusterReportedCustomCA, optional) — Custom CA bundle reported by the cluster for a specific consumer (git-sync, S3, oauth2-proxy).
- `customCAOauth2Proxy` (ClusterReportedCustomCA, optional) — Custom CA bundle reported by the cluster for a specific consumer (git-sync, S3, oauth2-proxy).
- `externalAuthUrlEnabled` (boolean, optional, nullable) — indicates if OAuth2 proxy is used when submitting workloads with an external URL
- `openshiftRouteTerminationPolicy` (enum, optional) — TLS termination policy for Run:ai-generated OpenShift Routes.
  - Allowed values: `edge`, `passthrough`
- `distGPUNetworkAcceleration` (boolean, optional, nullable) — indicates if GPU network acceleration (MNNVL) is enabled for the workload-controller (distributed-training)
- `dinfGPUNetworkAcceleration` (boolean, optional, nullable) — indicates if GPU network acceleration (MNNVL) is enabled for the inference-workload-controller (distributed-inference)

### ClusterDependenciesStatus

- `required` (map from string to ClusterDependencyStatus, required)
- `optional` (map from string to ClusterDependencyStatus, required)

### ClusterReportedStatusOperands

Status specifies the status of an operand. And operand manages resources, some of which are not immediately available and need their status monitored, such as Deployments, Daemonsets, Ingressess etc. Some resources are immediately available and should not be monitored once accepted by the cluster, such as Services, ConfigMaps, Secrets etc. If all resources of an operand are ready, a Status with Ready set to 'true' and a nil 'Reasons' slice should be returned, otherwise, a Status with 'Reasons' slice containig the reason why the Operand is not ready (Deployment pods are not ready for example.)

- `ready` (boolean, required) — Ready specifies if the operand is ready or not
- `lastTransitionTime` (datetime, optional) — LastTransitionTime specifies the last time the operand readiness changed
- `reasons` (list of string, optional) — Reasons specifies the reasons why the operand is not ready
- `unreadyThresholdCrossed` (boolean, optional) — UnreadyThresholdCrossed specifies if the operand has been unready for longer than the threshold

### ClusterReportedStatusPlatform

- `type` (enum, optional, nullable) — the cluster platform type
  - Allowed values: `vanilla`, `openshift`, `rke`, `gke`, `aks`, `eks`
- `kubeVersion` (string, optional, nullable) — the cluster kubernetes version

### ClusterReportedResourceRequirements

Resource requests and limits reported by a cluster for a composed container.

- `limits` (map from string to string, optional) — Resource limits keyed by Kubernetes resource name.
- `requests` (map from string to string, optional) — Resource requests keyed by Kubernetes resource name.

### ClusterReportedCustomCA

Custom CA bundle reported by the cluster for a specific consumer (git-sync, S3, oauth2-proxy).

- `enabled` (boolean, optional, nullable) — indicates if a custom CA bundle is configured for this consumer
- `secretName` (string, optional, nullable) — the name of the Secret holding the custom CA bundle
- `secretKey` (string, optional, nullable) — the key within the Secret that holds the custom CA bundle
- `optional` (boolean, optional, nullable) — indicates if the Secret is optional (the consumer should tolerate a missing Secret)

### ClusterDependencyStatus

- `available` (boolean, required) — whether the dependency is available
- `reason` (string, optional) — the reason for the dependency status
- `components` (map from string to ClusterDependencyStatus, optional)

## Examples

**Response**

```json
{
  "uuid": "A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11",
  "tenantId": 1001,
  "name": "example",
  "createdAt": "2020-01-01T00:00:00Z",
  "domain": "my.company.com",
  "version": "2.15.0",
  "status": {},
  "updatedAt": "2020-01-02T00:00:00Z",
  "lastLiveness": "2020-01-02T00:00:00Z"
}
```

**SDK Code**

```python
import requests

url = "http://localhost:8080/api/v1/clusters/9f55255e-11ed-47c7-acef-fc4054768dbc"

querystring = {"verbosity":"full"}

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

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

print(response.json())
```

```javascript
const url = 'http://localhost:8080/api/v1/clusters/9f55255e-11ed-47c7-acef-fc4054768dbc?verbosity=full';
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/clusters/9f55255e-11ed-47c7-acef-fc4054768dbc?verbosity=full"

	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/clusters/9f55255e-11ed-47c7-acef-fc4054768dbc?verbosity=full")

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/clusters/9f55255e-11ed-47c7-acef-fc4054768dbc?verbosity=full")
  .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/clusters/9f55255e-11ed-47c7-acef-fc4054768dbc?verbosity=full', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("http://localhost:8080/api/v1/clusters/9f55255e-11ed-47c7-acef-fc4054768dbc?verbosity=full");
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/clusters/9f55255e-11ed-47c7-acef-fc4054768dbc?verbosity=full")! 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()
```