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

bearerAuth

AuthorizationstringRequired

Bearer authentication

Query parameters

filterBystring[]Optional

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","[email protected]"]

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

HTTPcURLJavaScriptPython

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-03-20T13:02:11.748Z",
      "createdBy": "[email protected]",
      "phase": "Ready",
      "source": "Run.ai",
      "nodePools": [
        "a100"
      ]
    }
  ]
}

Create network topologies

post

Creates a network topology object based on the provided specification.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Body

application/json

levelsstring[]Required

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

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

HTTPcURLJavaScriptPython

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-03-20T13:02:11.748Z",
  "createdBy": "[email protected]",
  "phase": "Ready",
  "source": "Run.ai",
  "nodePools": [
    "a100"
  ]
}

Count the amount of network topologies in a tenant.

get

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

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Query parameters

filterBystring[]Optional

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","[email protected]"]

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

HTTPcURLJavaScriptPython

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

bearerAuth

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[]Required

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: [email protected]

phasestringOptional

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

Example: Ready

sourcestring · min: 1 · max: 63Optional

Identifier of the the source of the topology. Useful for tracking where the topology data originated (i.e. Run:ai, Cluster).

Example: Run.aiPattern: ^[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}

HTTPcURLJavaScriptPython

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-03-20T13:02:11.748Z",
  "createdBy": "[email protected]",
  "phase": "Ready",
  "source": "Run.ai",
  "nodePools": [
    "a100"
  ]
}

Delete network topology by ID.

delete

Delete an existing network topology by its ID.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication

Path parameters

networkTopologyIdstring · uuidRequired

The unique identifier for the network topology

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

Responses

204

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}

HTTPcURLJavaScriptPython

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

No content