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.

Deprecated

Get a list of nodes.

get

Retrieve a list of nodes from the Kubernetes cluster. Deprecated - use /api/v1/nodes instead.

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

Deprecated - use filterBy instead. The node name; Cannot be used together with filterBy, sort, offset, limit or search query params.

filterBystring[]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 >=.

Example: ["name!=some-name"]

sortBystring · enumOptional

Sort results by a parameters.

Possible values:

sortOrderstring · enumOptional

Sort results in descending or ascending order.

Default: ascPossible values:

offsetinteger · int32Optional

The offset of the first item returned in the collection.

Example: 100

limitinteger · int32 · min: 1 · max: 500Optional

The maximum number of entries to return.

Default: 50

searchstringOptional

Filter results by a free text search.

Example: test project

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-05T00:03:03.102Z",
      "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-05T00:03:03.102Z"
    }
  ]
}

Count nodes

get

Count nodes

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

filterBystring[]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 >=.

Example: ["name!=some-name"]

searchstringOptional

Filter results by a free text search.

Example: test project

Responses

200

ok

application/json

400

Bad request.

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

unexpected error

application/json

503

unexpected error

application/json

get

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

HTTPcURLJavaScriptPython

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

{
  "count": 1
}

Get a list of nodes.

get

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

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Query parameters

filterBystring[]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 >=.

Example: ["name!=some-name"]

sortBystring · enumOptional

Sort results by a parameters.

Possible values:

sortOrderstring · enumOptional

Sort results in descending or ascending order.

Default: ascPossible values:

offsetinteger · int32Optional

The offset of the first item returned in the collection.

Example: 100

limitinteger · int32 · min: 1 · max: 500Optional

The maximum number of entries to return.

Default: 50

searchstringOptional

Filter results by a free text search.

Example: test project

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/nodes

HTTPcURLJavaScriptPython

GET /api/v1/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-05T00:03:03.102Z",
      "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-05T00:03:03.102Z"
    }
  ]
}

Count tenant nodes

get

Count nodes from all the Kubernetes clusters of the tenant.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Query parameters

filterBystring[]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 >=.

Example: ["name!=some-name"]

searchstringOptional

Filter results by a free text search.

Example: test project

Responses

200

ok

application/json

400

Bad request.

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

500

unexpected error

application/json

503

unexpected error

application/json

get

/api/v1/nodes/count

HTTPcURLJavaScriptPython

GET /api/v1/nodes/count HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "count": 1
}

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"
        }
      ]
    }
  ]
}