# 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.

> Retrieve a list of network topologies with details.

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"latest"},"tags":[{"name":"Network Topologies","description":"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."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"NetworkTopologiesFilterBy":{"name":"filterBy","in":"query","required":false,"description":"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: ==, !=, <=, >=.","schema":{"type":"array","maxItems":10,"items":{"type":"string","pattern":"^(name|clusterId|source|phase)(==|!=|<=|>=|=@|!@|=\\^|=\\$).+$"}},"explode":false}},"schemas":{"NetworkTopology":{"allOf":[{"$ref":"#/components/schemas/NetworkTopologyCreateRequest"},{"type":"object","required":["id","tenantId","createdAt","status"],"properties":{"id":{"$ref":"#/components/schemas/NetworkTopologyId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp for when the network topology was created"},"createdBy":{"type":"string","description":"Identifier of the user who created the network topology"},"phase":{"type":"string","description":"Phase of the network topology in the cluster. Enum: Creating, Ready"},"source":{"$ref":"#/components/schemas/NetworkTopologiesSource"},"nodePools":{"type":"array","items":{"type":"string"},"nullable":true,"readOnly":true,"description":"List of node-pools associated with this network topology"}}}]},"NetworkTopologyCreateRequest":{"allOf":[{"$ref":"#/components/schemas/NetworkTopologyUpdateFields"},{"type":"object","required":["name","clusterId"],"properties":{"name":{"$ref":"#/components/schemas/NetworkTopologyName"},"clusterId":{"$ref":"#/components/schemas/ClusterId"}}}]},"NetworkTopologyUpdateFields":{"type":"object","required":["levels"],"properties":{"levels":{"$ref":"#/components/schemas/NetworkTopologyLevels"}}},"NetworkTopologyLevels":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","pattern":"^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\\/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$","minLength":1,"maxLength":63},"description":"Ordered array of network topology levels"},"NetworkTopologyName":{"type":"string","description":"Name of the network topology","maxLength":63,"minLength":1,"pattern":"^[a-z]([a-z0-9-]*[a-z0-9])?$"},"ClusterId":{"description":"The id of the cluster.","type":"string","format":"uuid"},"NetworkTopologyId":{"type":"string","format":"uuid","description":"The unique identifier for the network topology"},"TenantId":{"description":"The id of the tenant.","type":"integer","format":"int32"},"NetworkTopologiesSource":{"type":"string","description":"Identifier of the the source of the topology. Useful for tracking where the topology data originated (i.e. Run:ai, Cluster).","minLength":1,"maxLength":63,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.-]*[a-zA-Z0-9]$"},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/network-topologies":{"get":{"summary":"Get network topologies.","description":"Retrieve a list of network topologies with details.","operationId":"get_network_topologies","tags":["Network Topologies"],"parameters":[{"$ref":"#/components/parameters/NetworkTopologiesFilterBy"}],"responses":{"200":{"description":"Executed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"networkTopologies":{"type":"array","items":{"$ref":"#/components/schemas/NetworkTopology"}}}}}}},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```

## Create network topologies

> Creates a network topology object based on the provided specification.

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"latest"},"tags":[{"name":"Network Topologies","description":"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."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"schemas":{"NetworkTopologyCreateRequest":{"allOf":[{"$ref":"#/components/schemas/NetworkTopologyUpdateFields"},{"type":"object","required":["name","clusterId"],"properties":{"name":{"$ref":"#/components/schemas/NetworkTopologyName"},"clusterId":{"$ref":"#/components/schemas/ClusterId"}}}]},"NetworkTopologyUpdateFields":{"type":"object","required":["levels"],"properties":{"levels":{"$ref":"#/components/schemas/NetworkTopologyLevels"}}},"NetworkTopologyLevels":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","pattern":"^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\\/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$","minLength":1,"maxLength":63},"description":"Ordered array of network topology levels"},"NetworkTopologyName":{"type":"string","description":"Name of the network topology","maxLength":63,"minLength":1,"pattern":"^[a-z]([a-z0-9-]*[a-z0-9])?$"},"ClusterId":{"description":"The id of the cluster.","type":"string","format":"uuid"},"NetworkTopology":{"allOf":[{"$ref":"#/components/schemas/NetworkTopologyCreateRequest"},{"type":"object","required":["id","tenantId","createdAt","status"],"properties":{"id":{"$ref":"#/components/schemas/NetworkTopologyId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp for when the network topology was created"},"createdBy":{"type":"string","description":"Identifier of the user who created the network topology"},"phase":{"type":"string","description":"Phase of the network topology in the cluster. Enum: Creating, Ready"},"source":{"$ref":"#/components/schemas/NetworkTopologiesSource"},"nodePools":{"type":"array","items":{"type":"string"},"nullable":true,"readOnly":true,"description":"List of node-pools associated with this network topology"}}}]},"NetworkTopologyId":{"type":"string","format":"uuid","description":"The unique identifier for the network topology"},"TenantId":{"description":"The id of the tenant.","type":"integer","format":"int32"},"NetworkTopologiesSource":{"type":"string","description":"Identifier of the the source of the topology. Useful for tracking where the topology data originated (i.e. Run:ai, Cluster).","minLength":1,"maxLength":63,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.-]*[a-zA-Z0-9]$"},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"400BadRequest":{"description":"Bad request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/network-topologies":{"post":{"summary":"Create network topologies","description":"Creates a network topology object based on the provided specification.","operationId":"create_network_topology","tags":["Network Topologies"],"requestBody":{"description":"The network topology to create.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NetworkTopologyCreateRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NetworkTopology"}}}},"400":{"$ref":"#/components/responses/400BadRequest"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```

## Count the amount of network topologies in a tenant.

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

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"latest"},"tags":[{"name":"Network Topologies","description":"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."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"NetworkTopologiesFilterBy":{"name":"filterBy","in":"query","required":false,"description":"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: ==, !=, <=, >=.","schema":{"type":"array","maxItems":10,"items":{"type":"string","pattern":"^(name|clusterId|source|phase)(==|!=|<=|>=|=@|!@|=\\^|=\\$).+$"}},"explode":false}},"schemas":{"CountResponse":{"type":"object","required":["count"],"properties":{"count":{"type":"integer","format":"int64"}}},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/network-topologies/count":{"get":{"summary":"Count the amount of network topologies in a tenant.","description":"Retrieve the count of network topologies in a tenant group by selected attributes","operationId":"get_network_topologies_count","tags":["Network Topologies"],"parameters":[{"$ref":"#/components/parameters/NetworkTopologiesFilterBy"}],"responses":{"200":{"description":"Executed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountResponse"}}}},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```

## Get network topology by id.

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

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"latest"},"tags":[{"name":"Network Topologies","description":"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."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"NetworkTopologyId":{"name":"networkTopologyId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique identifier for the network topology"}},"schemas":{"NetworkTopology":{"allOf":[{"$ref":"#/components/schemas/NetworkTopologyCreateRequest"},{"type":"object","required":["id","tenantId","createdAt","status"],"properties":{"id":{"$ref":"#/components/schemas/NetworkTopologyId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp for when the network topology was created"},"createdBy":{"type":"string","description":"Identifier of the user who created the network topology"},"phase":{"type":"string","description":"Phase of the network topology in the cluster. Enum: Creating, Ready"},"source":{"$ref":"#/components/schemas/NetworkTopologiesSource"},"nodePools":{"type":"array","items":{"type":"string"},"nullable":true,"readOnly":true,"description":"List of node-pools associated with this network topology"}}}]},"NetworkTopologyCreateRequest":{"allOf":[{"$ref":"#/components/schemas/NetworkTopologyUpdateFields"},{"type":"object","required":["name","clusterId"],"properties":{"name":{"$ref":"#/components/schemas/NetworkTopologyName"},"clusterId":{"$ref":"#/components/schemas/ClusterId"}}}]},"NetworkTopologyUpdateFields":{"type":"object","required":["levels"],"properties":{"levels":{"$ref":"#/components/schemas/NetworkTopologyLevels"}}},"NetworkTopologyLevels":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","pattern":"^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\\/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$","minLength":1,"maxLength":63},"description":"Ordered array of network topology levels"},"NetworkTopologyName":{"type":"string","description":"Name of the network topology","maxLength":63,"minLength":1,"pattern":"^[a-z]([a-z0-9-]*[a-z0-9])?$"},"ClusterId":{"description":"The id of the cluster.","type":"string","format":"uuid"},"NetworkTopologyId":{"type":"string","format":"uuid","description":"The unique identifier for the network topology"},"TenantId":{"description":"The id of the tenant.","type":"integer","format":"int32"},"NetworkTopologiesSource":{"type":"string","description":"Identifier of the the source of the topology. Useful for tracking where the topology data originated (i.e. Run:ai, Cluster).","minLength":1,"maxLength":63,"pattern":"^[a-zA-Z0-9][a-zA-Z0-9_.-]*[a-zA-Z0-9]$"},"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}},"responses":{"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/network-topologies/{networkTopologyId}":{"get":{"summary":"Get network topology by id.","description":"Retrieve network topology details by Universally Unique Identifier (UUID).","operationId":"get_network_topology_by_id","tags":["Network Topologies"],"parameters":[{"$ref":"#/components/parameters/NetworkTopologyId"}],"responses":{"200":{"description":"Executed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NetworkTopology"}}}},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```

## Delete network topology by ID.

> Delete an existing network topology by its ID.

```json
{"openapi":"3.0.3","info":{"title":"NVIDIA Run:ai","version":"latest"},"tags":[{"name":"Network Topologies","description":"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."}],"servers":[{"url":"https://app.run.ai"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer authentication"}},"parameters":{"NetworkTopologyId":{"name":"networkTopologyId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The unique identifier for the network topology"}},"responses":{"204NoContent":{"description":"No Content."},"401Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404NotFound":{"description":"The specified resource was not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500InternalServerError":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503ServiceUnavailable":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"required":["code","message"],"properties":{"code":{"type":"integer","minimum":100,"maximum":599},"message":{"type":"string"},"details":{"type":"string"}}}}},"paths":{"/api/v1/network-topologies/{networkTopologyId}":{"delete":{"summary":"Delete network topology by ID.","description":"Delete an existing network topology by its ID.","operationId":"delete_network_topology","tags":["Network Topologies"],"parameters":[{"$ref":"#/components/parameters/NetworkTopologyId"}],"responses":{"204":{"$ref":"#/components/responses/204NoContent"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerError"},"503":{"$ref":"#/components/responses/503ServiceUnavailable"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://run-ai-docs.nvidia.com/api/organizations/network-topologies.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.