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-02-05T00:09:48.798Z",
      "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

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-02-05T00:09:48.798Z",
  "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

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

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-02-05T00:09:48.798Z",
  "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