> For the complete documentation index, see [llms.txt](https://run-ai-docs.nvidia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://run-ai-docs.nvidia.com/api/2.26/organizations/clusters.md).
# Clusters
Use these endpoints to create, manage and delete NVIDIA Run:ai Kubernetes clusters.
## Get a list of clusters.
> Retrieve a list of clusters with details.
```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.26"},"tags":[{"name":"Clusters","description":"Use these endpoints to create, manage and delete NVIDIA Run:ai Kubernetes clusters."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"QueryVerbosity":{"name":"verbosity","in":"query","required":false,"description":"response verbosity level.\n","schema":{"type":"string","enum":["metadata","full"],"default":"full"}},"QueryIncludeRequestedForDelete":{"name":"includeRequestedForDelete","in":"query","required":false,"schema":{"type":"boolean"},"description":"When true, includes clusters that are marked for deletion"}},"schemas":{"DisplayedCluster":{"type":"object","required":["uuid","tenantId","name","createdAt"],"properties":{"uuid":{"type":"string","format":"uuid"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"name":{"type":"string","minLength":1,"maxLength":253},"createdAt":{"type":"string","format":"date-time"},"domain":{"type":"string","nullable":true,"minLength":1,"maxLength":253},"version":{"type":"string","nullable":true,"minLength":1,"maxLength":50},"status":{"$ref":"#/components/schemas/ClusterDisplayedStatus"},"updatedAt":{"type":"string","format":"date-time","nullable":true},"deletedAt":{"type":"string","nullable":true,"format":"date-time"},"lastLiveness":{"type":"string","nullable":true,"format":"date-time"},"deleteRequestedAt":{"description":"the timestamp value of when the cluster deletion request was received","type":"string","format":"date-time","nullable":true}}},"TenantId":{"description":"The id of the tenant.","type":"integer","format":"int32"},"ClusterDisplayedStatus":{"type":"object","description":"The cluster's displayed status.","nullable":true,"allOf":[{"$ref":"#/components/schemas/ClusterReportedStatus"},{"type":"object","properties":{"state":{"$ref":"#/components/schemas/ClusterState"}}}]},"ClusterReportedStatus":{"type":"object","description":"the cluster status reported by the cluster","properties":{"conditions":{"items":{"description":"Condition contains details for one aspect of the current state of this API Resource","properties":{"lastTransitionTime":{"description":"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.","format":"date-time","type":"string"},"message":{"description":"message is a human readable message indicating details about the transition. This may be an empty string.","maxLength":32768,"type":"string"},"observedGeneration":{"description":"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.","format":"int64","minimum":0,"type":"integer"},"reason":{"description":"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.","maxLength":1024,"minLength":1,"pattern":"^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$","type":"string"},"status":{"description":"status of the condition, one of True, False, Unknown.","enum":["True","False","Unknown"],"type":"string"},"type":{"description":"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)","maxLength":316,"type":"string"}},"required":["lastTransitionTime","message","reason","status","type"],"type":"object"},"type":"array"},"operands":{"additionalProperties":{"description":"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.)","properties":{"lastTransitionTime":{"description":"LastTransitionTime specifies the last time the operand readiness changed","format":"date-time","type":"string"},"ready":{"description":"Ready specifies if the operand is ready or not","type":"boolean"},"reasons":{"description":"Reasons specifies the reasons why the operand is not ready","items":{"type":"string"},"type":"array"},"unreadyThresholdCrossed":{"description":"UnreadyThresholdCrossed specifies if the operand has been unready for longer than the threshold","type":"boolean"}},"required":["ready"],"type":"object"},"description":"OperandStatuses specifies the status of the managed operands","type":"object"},"platform":{"$ref":"#/components/schemas/ClusterReportedStatusPlatform"},"config":{"$ref":"#/components/schemas/ClusterReportedConfig"},"dependencies":{"$ref":"#/components/schemas/ClusterDependenciesStatus"}}},"ClusterReportedStatusPlatform":{"nullable":true,"type":"object","properties":{"type":{"nullable":true,"type":"string","enum":["vanilla","openshift","rke","gke","aks","eks"],"description":"the cluster platform type"},"kubeVersion":{"nullable":true,"type":"string","description":"the cluster kubernetes version"}}},"ClusterReportedConfig":{"description":"Holds cluster configuration values.","type":"object","properties":{"workloadOwnershipProtection":{"type":"boolean","nullable":true,"description":"indicates if the cluster workload ownership protection is enabled"},"subdomainEnabled":{"type":"boolean","nullable":true,"description":"indicates if the cluster subdomain is enabled"},"ingressClass":{"type":"string","nullable":true,"description":"the ingress class that is configured for the cluster"},"ingressEnabled":{"type":"boolean","nullable":true,"description":"indicates if Ingress or Route resources should be created for workload external URLs"},"gatewayName":{"type":"string","nullable":true,"description":"the name of the Gateway API gateway resource configured for the cluster"},"gatewayNamespace":{"type":"string","nullable":true,"description":"the namespace of the Gateway API gateway resource configured for the cluster"},"gatewayAPIEnabled":{"type":"boolean","nullable":true,"description":"indicates if Gateway API HTTPRoute resources should be created for workload external URLs"},"gitSyncImage":{"type":"string","nullable":true,"description":"the fully qualified git-sync image reference used by init containers (format \"registry/name:tag\")"},"s3FileSystemImage":{"type":"string","nullable":true,"description":"the fully qualified s3 file-system image reference used by init containers (format \"registry/name:tag\")"},"runaiOauth2ProxyImage":{"type":"string","nullable":true,"description":"the fully qualified runai oauth2-proxy image reference used by init containers (format \"registry/name:tag\")"},"runaiOauth2ProxyUsernameLoaderImage":{"type":"string","nullable":true,"description":"the fully qualified runai oauth2-proxy username loader image reference used by init containers (format \"registry/name:tag\")"},"runaiOauth2ProxyRedisFQDN":{"type":"string","nullable":true,"description":"the FQDN of the Redis backing oauth2-proxy"},"runaiOauth2ProxyWorkloadAuthSecretName":{"type":"string","nullable":true,"description":"the name of the Secret holding the oauth2-proxy workload auth credentials"},"runaiOauth2ProxySessionStoreType":{"type":"string","nullable":true,"description":"the session store type used by oauth2-proxy"},"runaiOauth2ProxyOidcIssuerUrl":{"type":"string","nullable":true,"description":"the absolute OIDC issuer URL oauth2-proxy uses to discover the OpenID provider"},"customCAGit":{"$ref":"#/components/schemas/ClusterReportedCustomCA"},"customCAS3":{"$ref":"#/components/schemas/ClusterReportedCustomCA"},"customCAOauth2Proxy":{"$ref":"#/components/schemas/ClusterReportedCustomCA"},"externalAuthUrlEnabled":{"type":"boolean","nullable":true,"description":"indicates if OAuth2 proxy is used when submitting workloads with an external URL"}},"nullable":true},"ClusterReportedCustomCA":{"description":"Custom CA bundle reported by the cluster for a specific consumer (git-sync, S3, oauth2-proxy).","type":"object","nullable":true,"properties":{"enabled":{"type":"boolean","nullable":true,"description":"indicates if a custom CA bundle is configured for this consumer"},"secretName":{"type":"string","nullable":true,"description":"the name of the Secret holding the custom CA bundle"},"secretKey":{"type":"string","nullable":true,"description":"the key within the Secret that holds the custom CA bundle"},"optional":{"type":"boolean","nullable":true,"description":"indicates if the Secret is optional (the consumer should tolerate a missing Secret)"}}},"ClusterDependenciesStatus":{"type":"object","required":["required","optional"],"properties":{"required":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}},"optional":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}}}},"ClusterDependencyStatus":{"type":"object","required":["available"],"properties":{"available":{"type":"boolean","description":"whether the dependency is available"},"reason":{"type":"string","description":"the reason for the dependency status"},"components":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}}}},"ClusterState":{"type":"string","description":"The cluster's state.","enum":["WaitingToConnect","Connected","Disconnected","MissingPrerequisites","ServiceIssues","Unknown"]},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/clusters":{"get":{"summary":"Get a list of clusters.","description":"Retrieve a list of clusters with details.","operationId":"get_clusters","tags":["Clusters"],"parameters":[{"$ref":"#/components/parameters/QueryVerbosity"},{"$ref":"#/components/parameters/QueryIncludeRequestedForDelete"}],"responses":{"200":{"description":"Executed successfully.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/DisplayedCluster"}}}}},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```
## Create a cluster.
> Use to create a Kubernetes cluster.
```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.26"},"tags":[{"name":"Clusters","description":"Use these endpoints to create, manage and delete NVIDIA Run:ai Kubernetes clusters."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"schemas":{"ClusterCreationRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":0,"maxLength":253},"domain":{"type":"string","minLength":0,"maxLength":253},"version":{"type":"string","minLength":0,"maxLength":50}}},"DisplayedCluster":{"type":"object","required":["uuid","tenantId","name","createdAt"],"properties":{"uuid":{"type":"string","format":"uuid"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"name":{"type":"string","minLength":1,"maxLength":253},"createdAt":{"type":"string","format":"date-time"},"domain":{"type":"string","nullable":true,"minLength":1,"maxLength":253},"version":{"type":"string","nullable":true,"minLength":1,"maxLength":50},"status":{"$ref":"#/components/schemas/ClusterDisplayedStatus"},"updatedAt":{"type":"string","format":"date-time","nullable":true},"deletedAt":{"type":"string","nullable":true,"format":"date-time"},"lastLiveness":{"type":"string","nullable":true,"format":"date-time"},"deleteRequestedAt":{"description":"the timestamp value of when the cluster deletion request was received","type":"string","format":"date-time","nullable":true}}},"TenantId":{"description":"The id of the tenant.","type":"integer","format":"int32"},"ClusterDisplayedStatus":{"type":"object","description":"The cluster's displayed status.","nullable":true,"allOf":[{"$ref":"#/components/schemas/ClusterReportedStatus"},{"type":"object","properties":{"state":{"$ref":"#/components/schemas/ClusterState"}}}]},"ClusterReportedStatus":{"type":"object","description":"the cluster status reported by the cluster","properties":{"conditions":{"items":{"description":"Condition contains details for one aspect of the current state of this API Resource","properties":{"lastTransitionTime":{"description":"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.","format":"date-time","type":"string"},"message":{"description":"message is a human readable message indicating details about the transition. This may be an empty string.","maxLength":32768,"type":"string"},"observedGeneration":{"description":"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.","format":"int64","minimum":0,"type":"integer"},"reason":{"description":"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.","maxLength":1024,"minLength":1,"pattern":"^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$","type":"string"},"status":{"description":"status of the condition, one of True, False, Unknown.","enum":["True","False","Unknown"],"type":"string"},"type":{"description":"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)","maxLength":316,"type":"string"}},"required":["lastTransitionTime","message","reason","status","type"],"type":"object"},"type":"array"},"operands":{"additionalProperties":{"description":"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.)","properties":{"lastTransitionTime":{"description":"LastTransitionTime specifies the last time the operand readiness changed","format":"date-time","type":"string"},"ready":{"description":"Ready specifies if the operand is ready or not","type":"boolean"},"reasons":{"description":"Reasons specifies the reasons why the operand is not ready","items":{"type":"string"},"type":"array"},"unreadyThresholdCrossed":{"description":"UnreadyThresholdCrossed specifies if the operand has been unready for longer than the threshold","type":"boolean"}},"required":["ready"],"type":"object"},"description":"OperandStatuses specifies the status of the managed operands","type":"object"},"platform":{"$ref":"#/components/schemas/ClusterReportedStatusPlatform"},"config":{"$ref":"#/components/schemas/ClusterReportedConfig"},"dependencies":{"$ref":"#/components/schemas/ClusterDependenciesStatus"}}},"ClusterReportedStatusPlatform":{"nullable":true,"type":"object","properties":{"type":{"nullable":true,"type":"string","enum":["vanilla","openshift","rke","gke","aks","eks"],"description":"the cluster platform type"},"kubeVersion":{"nullable":true,"type":"string","description":"the cluster kubernetes version"}}},"ClusterReportedConfig":{"description":"Holds cluster configuration values.","type":"object","properties":{"workloadOwnershipProtection":{"type":"boolean","nullable":true,"description":"indicates if the cluster workload ownership protection is enabled"},"subdomainEnabled":{"type":"boolean","nullable":true,"description":"indicates if the cluster subdomain is enabled"},"ingressClass":{"type":"string","nullable":true,"description":"the ingress class that is configured for the cluster"},"ingressEnabled":{"type":"boolean","nullable":true,"description":"indicates if Ingress or Route resources should be created for workload external URLs"},"gatewayName":{"type":"string","nullable":true,"description":"the name of the Gateway API gateway resource configured for the cluster"},"gatewayNamespace":{"type":"string","nullable":true,"description":"the namespace of the Gateway API gateway resource configured for the cluster"},"gatewayAPIEnabled":{"type":"boolean","nullable":true,"description":"indicates if Gateway API HTTPRoute resources should be created for workload external URLs"},"gitSyncImage":{"type":"string","nullable":true,"description":"the fully qualified git-sync image reference used by init containers (format \"registry/name:tag\")"},"s3FileSystemImage":{"type":"string","nullable":true,"description":"the fully qualified s3 file-system image reference used by init containers (format \"registry/name:tag\")"},"runaiOauth2ProxyImage":{"type":"string","nullable":true,"description":"the fully qualified runai oauth2-proxy image reference used by init containers (format \"registry/name:tag\")"},"runaiOauth2ProxyUsernameLoaderImage":{"type":"string","nullable":true,"description":"the fully qualified runai oauth2-proxy username loader image reference used by init containers (format \"registry/name:tag\")"},"runaiOauth2ProxyRedisFQDN":{"type":"string","nullable":true,"description":"the FQDN of the Redis backing oauth2-proxy"},"runaiOauth2ProxyWorkloadAuthSecretName":{"type":"string","nullable":true,"description":"the name of the Secret holding the oauth2-proxy workload auth credentials"},"runaiOauth2ProxySessionStoreType":{"type":"string","nullable":true,"description":"the session store type used by oauth2-proxy"},"runaiOauth2ProxyOidcIssuerUrl":{"type":"string","nullable":true,"description":"the absolute OIDC issuer URL oauth2-proxy uses to discover the OpenID provider"},"customCAGit":{"$ref":"#/components/schemas/ClusterReportedCustomCA"},"customCAS3":{"$ref":"#/components/schemas/ClusterReportedCustomCA"},"customCAOauth2Proxy":{"$ref":"#/components/schemas/ClusterReportedCustomCA"},"externalAuthUrlEnabled":{"type":"boolean","nullable":true,"description":"indicates if OAuth2 proxy is used when submitting workloads with an external URL"}},"nullable":true},"ClusterReportedCustomCA":{"description":"Custom CA bundle reported by the cluster for a specific consumer (git-sync, S3, oauth2-proxy).","type":"object","nullable":true,"properties":{"enabled":{"type":"boolean","nullable":true,"description":"indicates if a custom CA bundle is configured for this consumer"},"secretName":{"type":"string","nullable":true,"description":"the name of the Secret holding the custom CA bundle"},"secretKey":{"type":"string","nullable":true,"description":"the key within the Secret that holds the custom CA bundle"},"optional":{"type":"boolean","nullable":true,"description":"indicates if the Secret is optional (the consumer should tolerate a missing Secret)"}}},"ClusterDependenciesStatus":{"type":"object","required":["required","optional"],"properties":{"required":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}},"optional":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}}}},"ClusterDependencyStatus":{"type":"object","required":["available"],"properties":{"available":{"type":"boolean","description":"whether the dependency is available"},"reason":{"type":"string","description":"the reason for the dependency status"},"components":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}}}},"ClusterState":{"type":"string","description":"The cluster's state.","enum":["WaitingToConnect","Connected","Disconnected","MissingPrerequisites","ServiceIssues","Unknown"]},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/clusters":{"post":{"summary":"Create a cluster.","description":"Use to create a Kubernetes cluster.","operationId":"create_cluster","tags":["Clusters"],"requestBody":{"description":"The cluster to create.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClusterCreationRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisplayedCluster"}}}},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```
## Get clusters minimal data
> Retrieve essential cluster data required for common operations (e.g., workload submission)
```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.26"},"tags":[{"name":"Clusters","description":"Use these endpoints to create, manage and delete NVIDIA Run:ai Kubernetes clusters."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"ClustersMinimalFilterBy":{"name":"filterBy","in":"query","required":false,"description":"Filter clusters by a parameter. Use the format field-name operator value. Operators are == Equals, != Not equals, <= Less than or equal, >= Greater than or equal. Dates are in ISO 8601 timestamp format and available for operators ==, !=, <= and >=.","schema":{"type":"array","maxItems":10,"items":{"type":"string","pattern":"^(name)(==|!=|<=|>=|=@|!@|=\\^|=\\$).+$"}},"explode":false},"Offset":{"name":"offset","in":"query","required":false,"description":"The offset of the first item returned in the collection.","schema":{"type":"integer","format":"int32"}},"Limit":{"name":"limit","in":"query","required":false,"description":"The maximum number of entries to return.","schema":{"type":"integer","format":"int32","default":50,"minimum":1,"maximum":500}}},"schemas":{"ClustersMinimalData":{"type":"object","required":["uuid","tenantId","name","createdAt"],"properties":{"uuid":{"type":"string","format":"uuid"},"name":{"type":"string","format":".*"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"version":{"type":"string","format":".*","nullable":true},"domain":{"type":"string","format":".*","nullable":true},"platform":{"$ref":"#/components/schemas/ClusterReportedStatusPlatform"},"state":{"$ref":"#/components/schemas/ClusterState"},"ingressClass":{"type":"string","nullable":true,"description":"the ingress class that is configured for the cluster"},"dependenciesStatus":{"$ref":"#/components/schemas/ClusterDependenciesStatus"}}},"TenantId":{"description":"The id of the tenant.","type":"integer","format":"int32"},"ClusterReportedStatusPlatform":{"nullable":true,"type":"object","properties":{"type":{"nullable":true,"type":"string","enum":["vanilla","openshift","rke","gke","aks","eks"],"description":"the cluster platform type"},"kubeVersion":{"nullable":true,"type":"string","description":"the cluster kubernetes version"}}},"ClusterState":{"type":"string","description":"The cluster's state.","enum":["WaitingToConnect","Connected","Disconnected","MissingPrerequisites","ServiceIssues","Unknown"]},"ClusterDependenciesStatus":{"type":"object","required":["required","optional"],"properties":{"required":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}},"optional":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}}}},"ClusterDependencyStatus":{"type":"object","required":["available"],"properties":{"available":{"type":"boolean","description":"whether the dependency is available"},"reason":{"type":"string","description":"the reason for the dependency status"},"components":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}}}},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"400BadRequest":{"description":"Bad request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/clusters/minimal":{"get":{"summary":"Get clusters minimal data","operationId":"get_clusters_minimal_data","description":"Retrieve essential cluster data required for common operations (e.g., workload submission)","tags":["Clusters"],"parameters":[{"$ref":"#/components/parameters/ClustersMinimalFilterBy"},{"$ref":"#/components/parameters/Offset"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"clusters":{"type":"array","items":{"$ref":"#/components/schemas/ClustersMinimalData"}}}}}}},"400":{"$ref":"#/components/responses/400BadRequest"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```
## Get cluster minimal data by id
> Retrieve essential data for a specific cluster by ID required for common operations (e.g., workload submission)
```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.26"},"tags":[{"name":"Clusters","description":"Use these endpoints to create, manage and delete NVIDIA Run:ai Kubernetes clusters."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"ClusterUuid":{"name":"clusterUuid","in":"path","required":true,"description":"The Universally Unique Identifier (UUID) of the cluster.","schema":{"type":"string","format":"uuid","minLength":1}}},"schemas":{"ClustersMinimalData":{"type":"object","required":["uuid","tenantId","name","createdAt"],"properties":{"uuid":{"type":"string","format":"uuid"},"name":{"type":"string","format":".*"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"version":{"type":"string","format":".*","nullable":true},"domain":{"type":"string","format":".*","nullable":true},"platform":{"$ref":"#/components/schemas/ClusterReportedStatusPlatform"},"state":{"$ref":"#/components/schemas/ClusterState"},"ingressClass":{"type":"string","nullable":true,"description":"the ingress class that is configured for the cluster"},"dependenciesStatus":{"$ref":"#/components/schemas/ClusterDependenciesStatus"}}},"TenantId":{"description":"The id of the tenant.","type":"integer","format":"int32"},"ClusterReportedStatusPlatform":{"nullable":true,"type":"object","properties":{"type":{"nullable":true,"type":"string","enum":["vanilla","openshift","rke","gke","aks","eks"],"description":"the cluster platform type"},"kubeVersion":{"nullable":true,"type":"string","description":"the cluster kubernetes version"}}},"ClusterState":{"type":"string","description":"The cluster's state.","enum":["WaitingToConnect","Connected","Disconnected","MissingPrerequisites","ServiceIssues","Unknown"]},"ClusterDependenciesStatus":{"type":"object","required":["required","optional"],"properties":{"required":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}},"optional":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}}}},"ClusterDependencyStatus":{"type":"object","required":["available"],"properties":{"available":{"type":"boolean","description":"whether the dependency is available"},"reason":{"type":"string","description":"the reason for the dependency status"},"components":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}}}},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"400BadRequest":{"description":"Bad request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/clusters/{clusterUuid}/minimal":{"get":{"summary":"Get cluster minimal data by id","operationId":"get_cluster_minimal_data_by_id","description":"Retrieve essential data for a specific cluster by ID required for common operations (e.g., workload submission)","tags":["Clusters"],"parameters":[{"$ref":"#/components/parameters/ClusterUuid"}],"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClustersMinimalData"}}}},"400":{"$ref":"#/components/responses/400BadRequest"},"404":{"$ref":"#/components/responses/404NotFound"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```
## Get cluster by id.
> Retrieve cluster details by Universally Unique Identifier (UUID).
```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.26"},"tags":[{"name":"Clusters","description":"Use these endpoints to create, manage and delete NVIDIA Run:ai Kubernetes clusters."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"ClusterUuid":{"name":"clusterUuid","in":"path","required":true,"description":"The Universally Unique Identifier (UUID) of the cluster.","schema":{"type":"string","format":"uuid","minLength":1}},"QueryVerbosity":{"name":"verbosity","in":"query","required":false,"description":"response verbosity level.\n","schema":{"type":"string","enum":["metadata","full"],"default":"full"}}},"schemas":{"DisplayedCluster":{"type":"object","required":["uuid","tenantId","name","createdAt"],"properties":{"uuid":{"type":"string","format":"uuid"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"name":{"type":"string","minLength":1,"maxLength":253},"createdAt":{"type":"string","format":"date-time"},"domain":{"type":"string","nullable":true,"minLength":1,"maxLength":253},"version":{"type":"string","nullable":true,"minLength":1,"maxLength":50},"status":{"$ref":"#/components/schemas/ClusterDisplayedStatus"},"updatedAt":{"type":"string","format":"date-time","nullable":true},"deletedAt":{"type":"string","nullable":true,"format":"date-time"},"lastLiveness":{"type":"string","nullable":true,"format":"date-time"},"deleteRequestedAt":{"description":"the timestamp value of when the cluster deletion request was received","type":"string","format":"date-time","nullable":true}}},"TenantId":{"description":"The id of the tenant.","type":"integer","format":"int32"},"ClusterDisplayedStatus":{"type":"object","description":"The cluster's displayed status.","nullable":true,"allOf":[{"$ref":"#/components/schemas/ClusterReportedStatus"},{"type":"object","properties":{"state":{"$ref":"#/components/schemas/ClusterState"}}}]},"ClusterReportedStatus":{"type":"object","description":"the cluster status reported by the cluster","properties":{"conditions":{"items":{"description":"Condition contains details for one aspect of the current state of this API Resource","properties":{"lastTransitionTime":{"description":"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.","format":"date-time","type":"string"},"message":{"description":"message is a human readable message indicating details about the transition. This may be an empty string.","maxLength":32768,"type":"string"},"observedGeneration":{"description":"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.","format":"int64","minimum":0,"type":"integer"},"reason":{"description":"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.","maxLength":1024,"minLength":1,"pattern":"^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$","type":"string"},"status":{"description":"status of the condition, one of True, False, Unknown.","enum":["True","False","Unknown"],"type":"string"},"type":{"description":"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)","maxLength":316,"type":"string"}},"required":["lastTransitionTime","message","reason","status","type"],"type":"object"},"type":"array"},"operands":{"additionalProperties":{"description":"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.)","properties":{"lastTransitionTime":{"description":"LastTransitionTime specifies the last time the operand readiness changed","format":"date-time","type":"string"},"ready":{"description":"Ready specifies if the operand is ready or not","type":"boolean"},"reasons":{"description":"Reasons specifies the reasons why the operand is not ready","items":{"type":"string"},"type":"array"},"unreadyThresholdCrossed":{"description":"UnreadyThresholdCrossed specifies if the operand has been unready for longer than the threshold","type":"boolean"}},"required":["ready"],"type":"object"},"description":"OperandStatuses specifies the status of the managed operands","type":"object"},"platform":{"$ref":"#/components/schemas/ClusterReportedStatusPlatform"},"config":{"$ref":"#/components/schemas/ClusterReportedConfig"},"dependencies":{"$ref":"#/components/schemas/ClusterDependenciesStatus"}}},"ClusterReportedStatusPlatform":{"nullable":true,"type":"object","properties":{"type":{"nullable":true,"type":"string","enum":["vanilla","openshift","rke","gke","aks","eks"],"description":"the cluster platform type"},"kubeVersion":{"nullable":true,"type":"string","description":"the cluster kubernetes version"}}},"ClusterReportedConfig":{"description":"Holds cluster configuration values.","type":"object","properties":{"workloadOwnershipProtection":{"type":"boolean","nullable":true,"description":"indicates if the cluster workload ownership protection is enabled"},"subdomainEnabled":{"type":"boolean","nullable":true,"description":"indicates if the cluster subdomain is enabled"},"ingressClass":{"type":"string","nullable":true,"description":"the ingress class that is configured for the cluster"},"ingressEnabled":{"type":"boolean","nullable":true,"description":"indicates if Ingress or Route resources should be created for workload external URLs"},"gatewayName":{"type":"string","nullable":true,"description":"the name of the Gateway API gateway resource configured for the cluster"},"gatewayNamespace":{"type":"string","nullable":true,"description":"the namespace of the Gateway API gateway resource configured for the cluster"},"gatewayAPIEnabled":{"type":"boolean","nullable":true,"description":"indicates if Gateway API HTTPRoute resources should be created for workload external URLs"},"gitSyncImage":{"type":"string","nullable":true,"description":"the fully qualified git-sync image reference used by init containers (format \"registry/name:tag\")"},"s3FileSystemImage":{"type":"string","nullable":true,"description":"the fully qualified s3 file-system image reference used by init containers (format \"registry/name:tag\")"},"runaiOauth2ProxyImage":{"type":"string","nullable":true,"description":"the fully qualified runai oauth2-proxy image reference used by init containers (format \"registry/name:tag\")"},"runaiOauth2ProxyUsernameLoaderImage":{"type":"string","nullable":true,"description":"the fully qualified runai oauth2-proxy username loader image reference used by init containers (format \"registry/name:tag\")"},"runaiOauth2ProxyRedisFQDN":{"type":"string","nullable":true,"description":"the FQDN of the Redis backing oauth2-proxy"},"runaiOauth2ProxyWorkloadAuthSecretName":{"type":"string","nullable":true,"description":"the name of the Secret holding the oauth2-proxy workload auth credentials"},"runaiOauth2ProxySessionStoreType":{"type":"string","nullable":true,"description":"the session store type used by oauth2-proxy"},"runaiOauth2ProxyOidcIssuerUrl":{"type":"string","nullable":true,"description":"the absolute OIDC issuer URL oauth2-proxy uses to discover the OpenID provider"},"customCAGit":{"$ref":"#/components/schemas/ClusterReportedCustomCA"},"customCAS3":{"$ref":"#/components/schemas/ClusterReportedCustomCA"},"customCAOauth2Proxy":{"$ref":"#/components/schemas/ClusterReportedCustomCA"},"externalAuthUrlEnabled":{"type":"boolean","nullable":true,"description":"indicates if OAuth2 proxy is used when submitting workloads with an external URL"}},"nullable":true},"ClusterReportedCustomCA":{"description":"Custom CA bundle reported by the cluster for a specific consumer (git-sync, S3, oauth2-proxy).","type":"object","nullable":true,"properties":{"enabled":{"type":"boolean","nullable":true,"description":"indicates if a custom CA bundle is configured for this consumer"},"secretName":{"type":"string","nullable":true,"description":"the name of the Secret holding the custom CA bundle"},"secretKey":{"type":"string","nullable":true,"description":"the key within the Secret that holds the custom CA bundle"},"optional":{"type":"boolean","nullable":true,"description":"indicates if the Secret is optional (the consumer should tolerate a missing Secret)"}}},"ClusterDependenciesStatus":{"type":"object","required":["required","optional"],"properties":{"required":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}},"optional":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}}}},"ClusterDependencyStatus":{"type":"object","required":["available"],"properties":{"available":{"type":"boolean","description":"whether the dependency is available"},"reason":{"type":"string","description":"the reason for the dependency status"},"components":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ClusterDependencyStatus"}}}},"ClusterState":{"type":"string","description":"The cluster's state.","enum":["WaitingToConnect","Connected","Disconnected","MissingPrerequisites","ServiceIssues","Unknown"]},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/clusters/{clusterUuid}":{"get":{"summary":"Get cluster by id.","description":"Retrieve cluster details by Universally Unique Identifier (UUID).","operationId":"get_cluster_by_uuid","tags":["Clusters"],"parameters":[{"$ref":"#/components/parameters/ClusterUuid"},{"$ref":"#/components/parameters/QueryVerbosity"}],"responses":{"200":{"description":"Executed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisplayedCluster"}}}},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```
## Update a cluster by id.
> Use to update the details of a Kubernetes cluster by Universally Unique Identifier (UUID).
```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.26"},"tags":[{"name":"Clusters","description":"Use these endpoints to create, manage and delete NVIDIA Run:ai Kubernetes clusters."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"ClusterUuid":{"name":"clusterUuid","in":"path","required":true,"description":"The Universally Unique Identifier (UUID) of the cluster.","schema":{"type":"string","format":"uuid","minLength":1}}},"schemas":{"ClusterUpdateRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":0,"maxLength":253}}},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"204NoContent":{"description":"No Content."},"400BadRequest":{"description":"Bad request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/clusters/{clusterUuid}":{"put":{"summary":"Update a cluster by id.","description":"Use to update the details of a Kubernetes cluster by Universally Unique Identifier (UUID).","operationId":"updateCluster","tags":["Clusters"],"parameters":[{"$ref":"#/components/parameters/ClusterUuid"}],"requestBody":{"description":"The cluster details to update","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClusterUpdateRequest"}}}},"responses":{"204":{"$ref":"#/components/responses/204NoContent"},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```
## Delete a cluster by id.
> Use to delete a cluster by Universally Unique Identifier (UUID). \
> Will return 202 for success if this api was called on a cluster that its version is >=2.20, \
> and force query param is false or not provided.\
> Will return 204 for success if force query param is true, or if cluster is in a version < 2.20
```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.26"},"tags":[{"name":"Clusters","description":"Use these endpoints to create, manage and delete NVIDIA Run:ai Kubernetes clusters."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"ClusterUuid":{"name":"clusterUuid","in":"path","required":true,"description":"The Universally Unique Identifier (UUID) of the cluster.","schema":{"type":"string","format":"uuid","minLength":1}},"QueryForceDelete":{"name":"force","in":"query","required":false,"description":"if true will force cluster instant deletion otherwise will start cluster graceful deletion process.\n","schema":{"type":"boolean","default":false}}},"responses":{"202Accepted":{"description":"Accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpResponse"}}}},"204NoContent":{"description":"No Content."},"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"HttpResponse":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"}}},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}}},"paths":{"/api/v1/clusters/{clusterUuid}":{"delete":{"summary":"Delete a cluster by id.","description":"Use to delete a cluster by Universally Unique Identifier (UUID). \nWill return 202 for success if this api was called on a cluster that its version is >=2.20, \nand force query param is false or not provided.\nWill return 204 for success if force query param is true, or if cluster is in a version < 2.20\n","operationId":"delete_cluster","tags":["Clusters"],"parameters":[{"$ref":"#/components/parameters/ClusterUuid"},{"$ref":"#/components/parameters/QueryForceDelete"}],"responses":{"202":{"$ref":"#/components/responses/202Accepted"},"204":{"$ref":"#/components/responses/204NoContent"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```
## Get the cluster metrics data.
> Retrieve the metrics data for a Kubernetes cluster by Universally Unique Identifier (UUID).
```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.26"},"tags":[{"name":"Clusters","description":"Use these endpoints to create, manage and delete NVIDIA Run:ai Kubernetes clusters."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"ClusterUuid":{"name":"clusterUuid","in":"path","required":true,"description":"The Universally Unique Identifier (UUID) of the cluster.","schema":{"type":"string","format":"uuid","minLength":1}},"StartRequired":{"name":"start","in":"query","description":"Start date of time range to fetch data in ISO 8601 timestamp format.","required":true,"schema":{"type":"string","format":"date-time"}},"EndRequired":{"name":"end","in":"query","description":"End date of time range to fetch data in ISO 8601 timestamp format.","required":true,"schema":{"type":"string","format":"date-time"}},"NumberOfSamples":{"name":"numberOfSamples","in":"query","description":"The number of samples to take in the specified time range.","required":false,"schema":{"type":"integer","maximum":1000,"minimum":0,"default":20}},"MetricsType":{"name":"metricType","in":"query","required":true,"description":"specifies what data to request","explode":false,"schema":{"type":"array","items":{"$ref":"#/components/schemas/MetricsType"}}},"ClusterMetricsGroupBy":{"name":"groupBy","in":"query","description":"Labels to group the returned metrics data by. Grouping availability depends on the selected metric type. Supported values: \"category\" (workload category) or \"node pool\".\n","explode":false,"required":false,"schema":{"type":"string","enum":["Category","Nodepool","Project","Department"]}},"FilterByNodepoolName":{"name":"nodepoolName","in":"query","description":"Filter using the nodepool.","required":false,"schema":{"type":"string"}}},"schemas":{"MetricsType":{"type":"string","description":"specifies what data to request","enum":["TOTAL_GPU_NODES","GPU_UTILIZATION","GPU_UTILIZATION_DISTRIBUTION","GPU_MEMORY_UTILIZATION","CPU_UTILIZATION","CPU_MEMORY_UTILIZATION","TOTAL_GPU","GPU_QUOTA","ALLOCATED_GPU","UNALLOCATED_GPU","AVG_WORKLOAD_WAIT_TIME","WORKLOADS_COUNT"]},"GroupedMetricsResponse":{"type":"object","required":["measurements"],"properties":{"measurements":{"type":"array","items":{"$ref":"#/components/schemas/GroupedMeasurementResponse"}}}},"GroupedMeasurementResponse":{"type":"object","required":["type","values"],"properties":{"type":{"type":"string","description":"specifies what data returned"},"labels":{"type":"object","nullable":true,"description":"labels of the metric measurement","additionalProperties":{"type":"string"}},"values":{"type":"array","nullable":true,"items":{"type":"object","required":["value","timestamp"],"properties":{"value":{"type":"string"},"timestamp":{"type":"string","format":"date-time","nullable":true}}}},"groups":{"type":"array","description":"Group information for this measurement","items":{"$ref":"#/components/schemas/GroupedMeasurementGroup"}}}},"GroupedMeasurementGroup":{"type":"object","required":["key","value"],"properties":{"key":{"type":"string","description":"The grouping key"},"value":{"type":"string","description":"The grouping value"}}},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"400BadRequest":{"description":"Bad request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422UnprocessableEntity":{"description":"Unprocessable entity - The request was well-formed but contains semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/clusters/{clusterUuid}/metrics":{"get":{"summary":"Get the cluster metrics data.","description":"Retrieve the metrics data for a Kubernetes cluster by Universally Unique Identifier (UUID).","operationId":"get_cluster_metrics","tags":["Clusters"],"parameters":[{"$ref":"#/components/parameters/ClusterUuid"},{"$ref":"#/components/parameters/StartRequired"},{"$ref":"#/components/parameters/EndRequired"},{"$ref":"#/components/parameters/NumberOfSamples"},{"$ref":"#/components/parameters/MetricsType"},{"$ref":"#/components/parameters/ClusterMetricsGroupBy"},{"$ref":"#/components/parameters/FilterByNodepoolName"}],"responses":{"200":{"description":"Executed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupedMetricsResponse"}},"text/csv":{}}},"207":{"description":"Partial success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupedMetricsResponse"}}}},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"422":{"$ref":"#/components/responses/422UnprocessableEntity"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```
## Retrieve the installation instructions of a cluster by ID.
> Use to retrieve installation instruction for a cluster by Universally Unique Identifier (UUID). \
> Supports clusters version 2.15 or above.
```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"2.26"},"tags":[{"name":"Clusters","description":"Use these endpoints to create, manage and delete NVIDIA Run:ai Kubernetes clusters."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"ClusterUuid":{"name":"clusterUuid","in":"path","required":true,"description":"The Universally Unique Identifier (UUID) of the cluster.","schema":{"type":"string","format":"uuid","minLength":1}},"ClusterVersion":{"name":"version","in":"query","required":true,"description":"The cluster version to install","schema":{"type":"string"}},"ClusterRemoteURL":{"name":"remoteClusterUrl","in":"query","required":false,"description":"The remote URL of the runai cluster","schema":{"type":"string"}}},"schemas":{"ClusterInstallationInfoResponse":{"type":"object","required":["installationStr","repositoryName","chartRepoURL","clientSecret"],"properties":{"installationStr":{"type":"string"},"repositoryName":{"type":"string"},"chartRepoURL":{"type":"string"},"clientSecret":{"type":"string"}}},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/clusters/{clusterUuid}/cluster-install-info":{"get":{"summary":"Retrieve the installation instructions of a cluster by ID.","description":"Use to retrieve installation instruction for a cluster by Universally Unique Identifier (UUID). \nSupports clusters version 2.15 or above.\n","operationId":"get_cluster_install_info_by_uuid","tags":["Clusters"],"parameters":[{"$ref":"#/components/parameters/ClusterUuid"},{"$ref":"#/components/parameters/ClusterVersion"},{"$ref":"#/components/parameters/ClusterRemoteURL"}],"responses":{"200":{"description":"Executed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClusterInstallationInfoResponse"}}}},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://run-ai-docs.nvidia.com/api/2.26/organizations/clusters.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.