Nodes

Nodes are worker machines in Kubernetes and may be either a virtual or a physical machine, depending on the cluster. Each Node is managed by the NVIDIA Run:ai control plane. For more information, see Nodes.

Get a list of nodes.

get

Retrieve a list of nodes from the Kubernetes cluster.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Path parameters

clusterUuidstring · uuid · min: 1Required

The Universally Unique Identifier (UUID) of the cluster.

Example: 9f55255e-11ed-47c7-acef-fc4054768dbc

Query parameters

nodeNamestringOptional

The node name.

Responses

200

Executed successfully.

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

The specified resource was not found

application/json

500

unexpected error

application/json

503

unexpected error

application/json

get

/api/v1/clusters/{clusterUuid}/nodes

HTTPcURLJavaScriptPython

GET /api/v1/clusters/{clusterUuid}/nodes HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "nodes": [
    {
      "status": "Ready",
      "conditions": [
        {
          "type": "text",
          "reason": "KubeletNotReady",
          "message": "container runtime status check may not have completed yet"
        }
      ],
      "taints": [
        {
          "key": "foo",
          "value": "bar",
          "effect": "NoSchedule"
        }
      ],
      "nodePool": "node-pool-1",
      "createdAt": "2026-02-08T07:11:43.861Z",
      "gpuInfo": {
        "gpuType": "Tesla-V100",
        "gpuCount": 1
      },
      "nvLinkDomainUid": "nvlink-domain-uid",
      "nvLinkCliqueId": "clique-id",
      "name": "worker-node-1",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "clusterUuid": "71f69d83-ba66-4822-adf5-55ce55efd210",
      "updatedAt": "2026-02-08T07:11:43.861Z"
    }
  ]
}

Get node telemetry data.

get

Retrieve node telemetry data for use in analysis applications.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Query parameters

clusterIdstring · uuidOptional

Filter using the Universally Unique Identifier (UUID) of the cluster.

Example: d73a738f-fab3-430a-8fa3-5241493d7128

nodepoolNamestringOptional

Filter using the nodepool.

Example: default

telemetryTypestring · enumRequired

specifies what data to request

Possible values:

Responses

200

Executed successfully.

application/jsontext/csv

400

Bad request.

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

The specified resource was not found

application/json

500

unexpected error

application/json

503

unexpected error

application/json

get

/api/v1/nodes/telemetry

HTTPcURLJavaScriptPython

GET /api/v1/nodes/telemetry?telemetryType=READY_GPU_NODES HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "type": "ALLOCATION_RATIO",
  "timestamp": "2023-06-06 12:09:18.211",
  "values": [
    {
      "value": "85",
      "groups": [
        {
          "key": "department",
          "value": "1",
          "name": "department-A"
        }
      ]
    }
  ]
}

Get the node metrics data.

get

Retrieve the node metrics data by Universally Unique Identifier (UUID).

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Path parameters

nodeIdstring · uuid · min: 1Required

The node UUID.

Example: 9f55255e-11ed-47c7-acef-fc4054768dbc

Query parameters

startstring · date-timeRequired

Start date of time range to fetch data in ISO 8601 timestamp format.

Example: 2023-06-06T12:09:18.211Z

endstring · date-timeRequired

End date of time range to fetch data in ISO 8601 timestamp format.

Example: 2023-06-07T12:09:18.211Z

numberOfSamplesinteger · max: 1000Optional

The number of samples to take in the specified time range.

Default: 20Example: 20

Responses

200

Executed successfully.

application/jsontext/csv

207

Partial success.

application/json

400

Bad request.

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

The specified resource was not found

application/json

500

unexpected error

application/json

503

unexpected error

application/json

get

/api/v1/nodes/{nodeId}/metrics

HTTPcURLJavaScriptPython

GET /api/v1/nodes/{nodeId}/metrics?metricType=GPU_UTILIZATION_PER_GPU&start=2023-06-06T12%3A09%3A18.211Z&end=2023-06-07T12%3A09%3A18.211Z HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "measurements": [
    {
      "type": "ALLOCATED_GPU",
      "labels": "{'gpu': '3'}",
      "values": [
        {
          "value": "85",
          "timestamp": "2023-06-06 12:09:18.211"
        }
      ]
    }
  ]
}