Network Topologies

The Network Topologies API enables administrators to reflect the hierarchical network topology connectivity of nodes in a data center, such as racks, blocks, and other organizational units, to improve pod scheduling decisions for communication-intensive AI/ML workloads. To support topology-aware scheduling, this API allows administrators to define a multi-level network topology element using ordered Kubernetes node labels that represent the network connectivity of nodes in the data center. Nodes are labeled with the same key-value pairs labels that represent their location in the data center network. These labels are used by the NVIDIA Run:ai Scheduler to prefer scheduling pods on nodes that are "closer" to each other, minimizing communication overhead and optimizing workload performance.

Get network topologies.

get

Retrieve a list of network topologies with details.

Authorizations

AuthorizationstringRequired

Bearer authentication

Query parameters

filterBystring[] · max: 10Optional

Filter results by a parameter. Use the format field-name operator value. Supported operators: == Equals != Not equals <= Less than or equal >= Greater than or equal =@ Contains !@ Does not contain =^ Starts with =$ Ends with Date values must be in ISO 8601 timestamp format. Only the following operators support dates: ==, !=, <=, >=.

Example: ["clusterId==123e4567-e89b-12d3-a456-426614174000","source=@Run.ai"]

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/network-topologies

GET /api/v1/network-topologies HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "networkTopologies": [
    {
      "levels": [
        "cloud.provider.com/topology-block",
        "cloud.provider.com/topology-rack",
        "kubernetes.io/hostname"
      ],
      "name": "default-topology",
      "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210"
    },
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "tenantId": 1001,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "createdBy": "user@lab.com",
      "phase": "Ready",
      "source": "control-plane",
      "nodePools": [
        "a100"
      ],
      "groveTopology": {
        "name": "text",
        "domains": [
          "text"
        ],
        "conditions": [
          {
            "type": "text",
            "status": "text",
            "reason": "text",
            "message": "text",
            "observedGeneration": 1
          }
        ]
      }
    }
  ]
}

Create network topologies

post

Creates a network topology object based on the provided specification.

Authorizations

AuthorizationstringRequired

Bearer authentication

Body

levelsstring[] · min: 1 · max: 10Required

Ordered array of network topology levels

Example: ["cloud.provider.com/topology-block","cloud.provider.com/topology-rack","kubernetes.io/hostname"]

namestring · min: 1 · max: 63Required

Name of the network topology

Example: default-topologyPattern: ^[a-z]([a-z0-9-]*[a-z0-9])?$

clusterIdstring · uuidRequired

The id of the cluster.

Example: 71f69d83-ba66-4822-adf5-55ce55efd210

Responses

201

Created

application/json

levelsstring[] · min: 1 · max: 10Required

Ordered array of network topology levels

Example: ["cloud.provider.com/topology-block","cloud.provider.com/topology-rack","kubernetes.io/hostname"]

namestring · min: 1 · max: 63Required

Name of the network topology

Example: default-topologyPattern: ^[a-z]([a-z0-9-]*[a-z0-9])?$

clusterIdstring · uuidRequired

The id of the cluster.

Example: 71f69d83-ba66-4822-adf5-55ce55efd210

idstring · uuidRequired

The unique identifier for the network topology

Example: 123e4567-e89b-12d3-a456-426614174000

tenantIdinteger · int32Required

The id of the tenant.

Example: 1001

createdAtstring · date-timeRequired

The timestamp for when the network topology was created

createdBystringOptional

Identifier of the user who created the network topology

Example: user@lab.com

phasestringOptional

Phase of the network topology in the cluster. Enum: Creating, Ready

Example: Ready

sourcestring · min: 1 · max: 63Optional

Identifier of the source of the topology. Useful for tracking where the topology data originated (e.g. control-plane, cluster).

Example: control-planePattern: ^[a-zA-Z0-9][a-zA-Z0-9_.-]*[a-zA-Z0-9]$

nodePoolsstring[] · nullableRead-onlyOptional

List of node-pools associated with this network topology

Example: ["a100"]

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

post/api/v1/network-topologies

POST /api/v1/network-topologies HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 185

{
  "levels": [
    "cloud.provider.com/topology-block",
    "cloud.provider.com/topology-rack",
    "kubernetes.io/hostname"
  ],
  "name": "default-topology",
  "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210"
}

{
  "levels": [
    "cloud.provider.com/topology-block",
    "cloud.provider.com/topology-rack",
    "kubernetes.io/hostname"
  ],
  "name": "default-topology",
  "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "tenantId": 1001,
  "createdAt": "2026-01-01T00:00:00.000Z",
  "createdBy": "user@lab.com",
  "phase": "Ready",
  "source": "control-plane",
  "nodePools": [
    "a100"
  ],
  "groveTopology": {
    "name": "text",
    "domains": [
      "text"
    ],
    "conditions": [
      {
        "type": "text",
        "status": "text",
        "reason": "text",
        "message": "text",
        "observedGeneration": 1
      }
    ]
  }
}

Count the amount of network topologies in a tenant.

get

Retrieve the count of network topologies in a tenant group by selected attributes

Authorizations

AuthorizationstringRequired

Bearer authentication

Query parameters

filterBystring[] · max: 10Optional

Example: ["clusterId==123e4567-e89b-12d3-a456-426614174000","source=@Run.ai"]

Responses

200

Executed successfully.

application/json

countinteger · int64RequiredExample: 1

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/network-topologies/count

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

{
  "count": 1
}

Get network topology by id.

get

Retrieve network topology details by Universally Unique Identifier (UUID).

Authorizations

AuthorizationstringRequired

Bearer authentication

Path parameters

networkTopologyIdstring · uuidRequired

The unique identifier for the network topology

Example: 123e4567-e89b-12d3-a456-426614174000

Responses

200

Executed successfully.

application/json

levelsstring[] · min: 1 · max: 10Required

Ordered array of network topology levels

Example: ["cloud.provider.com/topology-block","cloud.provider.com/topology-rack","kubernetes.io/hostname"]

namestring · min: 1 · max: 63Required

Name of the network topology

Example: default-topologyPattern: ^[a-z]([a-z0-9-]*[a-z0-9])?$

clusterIdstring · uuidRequired

The id of the cluster.

Example: 71f69d83-ba66-4822-adf5-55ce55efd210

idstring · uuidRequired

The unique identifier for the network topology

Example: 123e4567-e89b-12d3-a456-426614174000

tenantIdinteger · int32Required

The id of the tenant.

Example: 1001

createdAtstring · date-timeRequired

The timestamp for when the network topology was created

createdBystringOptional

Identifier of the user who created the network topology

Example: user@lab.com

phasestringOptional

Phase of the network topology in the cluster. Enum: Creating, Ready

Example: Ready

sourcestring · min: 1 · max: 63Optional

Identifier of the source of the topology. Useful for tracking where the topology data originated (e.g. control-plane, cluster).

Example: control-planePattern: ^[a-zA-Z0-9][a-zA-Z0-9_.-]*[a-zA-Z0-9]$

nodePoolsstring[] · nullableRead-onlyOptional

List of node-pools associated with this network topology

Example: ["a100"]

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/network-topologies/{networkTopologyId}

GET /api/v1/network-topologies/{networkTopologyId} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "levels": [
    "cloud.provider.com/topology-block",
    "cloud.provider.com/topology-rack",
    "kubernetes.io/hostname"
  ],
  "name": "default-topology",
  "clusterId": "71f69d83-ba66-4822-adf5-55ce55efd210",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "tenantId": 1001,
  "createdAt": "2026-01-01T00:00:00.000Z",
  "createdBy": "user@lab.com",
  "phase": "Ready",
  "source": "control-plane",
  "nodePools": [
    "a100"
  ],
  "groveTopology": {
    "name": "text",
    "domains": [
      "text"
    ],
    "conditions": [
      {
        "type": "text",
        "status": "text",
        "reason": "text",
        "message": "text",
        "observedGeneration": 1
      }
    ]
  }
}

Delete network topology by ID.

delete

Delete an existing network topology by its ID.

Authorizations

AuthorizationstringRequired

Bearer authentication

Path parameters

networkTopologyIdstring · uuidRequired

The unique identifier for the network topology

Example: 123e4567-e89b-12d3-a456-426614174000

Responses

204

No Content.

No content

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

delete/api/v1/network-topologies/{networkTopologyId}

DELETE /api/v1/network-topologies/{networkTopologyId} HTTP/1.1
Host: app.run.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

PreviousResearcher Command Line Interface Deprecated NextAccess Keys

Last updated 15 days ago