Ctrlk
Contact support
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Count nodes

get

Count nodes

Authorizations
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[] · max: 10Optional

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
countinteger · int64Required
get/api/v1/clusters/{clusterUuid}/nodes/count
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
AuthorizationstringRequired

Bearer authentication

Query parameters
filterBystring[] · max: 10Optional

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
get/api/v1/nodes
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-01-01T00:00:00.000Z",
      "gpuInfo": {
        "gpuType": "Tesla-V100",
        "gpuCount": 1
      },
      "nvLinkDomainUid": "nvlink-domain-uid",
      "nvLinkCliqueId": "clique-id",
      "networkTopologyLabels": [
        {
          "labelKey": "text",
          "labelValue": "text"
        }
      ],
      "name": "worker-node-1",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "clusterUuid": "71f69d83-ba66-4822-adf5-55ce55efd210",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Count tenant nodes

get

Count nodes from all the Kubernetes clusters of the tenant.

Authorizations
AuthorizationstringRequired

Bearer authentication

Query parameters
filterBystring[] · max: 10Optional

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
countinteger · int64Required
get/api/v1/nodes/count
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
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.

typestringRequired

specifies what data returned

Example: ALLOCATION_RATIO
timestampstring · date-timeRequiredExample: 2023-06-06 12:09:18.211
get/api/v1/nodes/telemetry
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
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.

get/api/v1/nodes/{nodeId}/metrics
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"
        }
      ]
    }
  ]
}
PreviousNode PoolsNextProjects

Last updated