List Deployment Targets
const url = 'https://example.com/topology/v1/targets';const options = {method: 'GET'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://example.com/topology/v1/targetsReturns a paginated list of deployment targets filtered by optional parameters
Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”The maximum number of deployment targets to return. The service may return fewer than this value. If unspecified, at most 20 deployment targets will be returned. The maximum value is 100; values above 100 will be coerced to 100.
A page token, received from a previous ListDeploymentTargets call.
Provide this to retrieve the subsequent page.
When paginating, all other parameters provided to ListDeploymentTargets must match
the call that provided the page token.
A filter expression allows you to filter the deployment targets listed in the response.
At qibdo, we use the AIP-160 proposal, that means that your expression should include:
field name, an operator, and the value you wish to filter by.
The value can be a string, number, or boolean, and the operator must be one of the following: =, !=, >, <, <=, >=, or :
You can group multiple expressions using parentheses and the logical operators AND and OR.
Examples:
name = "host-01" -> Filter by deployment target name
hostname = "node1.qibdo.local" -> Filter by hostname
cpu_topology.architecture = "CPU_ARCHITECTURE_X86_64" -> Filter by CPU architecture
The order in which to sort the results. If not specified, the results will be sorted by name in ascending order.
At qibdo, we use the AIP-132 proposal, that means:
Values should be a comma separated list of fields. For example: "foo,bar".
The default sort order is ascending. To specify descending order, a suffix " desc" should be added. For example: "foo desc,bar".
Redundant space characters in the syntax are insignificant.
Responses
Section titled “ Responses ”OK
ListDeploymentTargetsResponse
Response message for ListDeploymentTargets.
Note: This API intentionally omits total_size from list responses.
Keyset pagination does not support efficient total count computation
(COUNT(*) requires a full table scan). Per AIP-158, total_size is optional.
object
The list of deployment targets
Deployment Target
Represents a physical host (deployment target) within a resource pool in the Qibdo Cloud topology. A deployment target contains full hardware specifications including CPU topology, GPU topology, memory topology, disk nodes, and network information.
object
The unique identifier of the deployment target
The unique identifier of the parent resource pool (optional — a deployment target can exist without belonging to a resource pool)
The display name of the deployment target (RFC 1035 DNS label)
The hostname of the physical host (RFC 1123 FQDN, max 253)
The operating system running on the host
object
The OS family (e.g., “Linux”, “Windows”)
The OS manufacturer (e.g., “Canonical”, “Microsoft”)
The OS version (e.g., “22.04”, “11”)
The bitness of the operating system
The CPU topology of the host
object
The byte order of the CPU
The CPU vendor identifier (e.g., “GenuineIntel”, “AuthenticAMD”)
The CPU model name (e.g., “Intel(R) Xeon(R) Gold 6248R”)
The CPU model number
The CPU family identifier
The CPU stepping (revision within a model)
The minimum clock frequency of the CPU
object
The numerical value of the clock speed
The unit of the clock speed value
The maximum clock frequency of the CPU
object
The numerical value of the clock speed
The unit of the clock speed value
The number of online (available) CPUs. In hybrid architectures this number won’t necessarily match the formula: threads_per_core x cores_per_socket x sockets
The number of threads per physical core
The number of physical cores per socket
The number of CPU sockets
The CPU architecture
The CPU caches (L1, L2, L3, etc.)
CPU Cache
Represents a single level of CPU cache (L1, L2, L3, etc.).
object
The cache level (1, 2, 3, etc.)
The cache size in bytes
The NUMA topology of the CPU
object
The list of NUMA nodes
NUMA Node
Represents a single NUMA node with its associated CPUs.
object
The NUMA node identifier
The list of CPU identifiers belonging to this NUMA node
The GPU topology of the host (may have zero or more GPUs)
GPU Topology
Describes a GPU installed on the physical host, including clock speeds, VRAM, core count, and AI-specific features.
object
The GPU name (e.g., “NVIDIA A100”, “AMD Instinct MI300X”)
The GPU device identifier
The GPU vendor (e.g., “NVIDIA”, “AMD”, “Intel”)
The base clock speed of the GPU
object
The numerical value of the clock speed
The unit of the clock speed value
The boost clock speed of the GPU
object
The numerical value of the clock speed
The unit of the clock speed value
The theoretical peak performance in TFLOPS
The GPU video RAM
object
The total VRAM size
object
The numerical value of the size
The unit of the size value
The type of VRAM
The memory bus width
object
The numerical value of the size
The unit of the size value
The number of GPU cores (CUDA cores, stream processors, etc.)
AI-specific features of the GPU
object
The number of tensor cores (NVIDIA) or equivalent
The number of ray tracing cores
Whether DLSS (Deep Learning Super Sampling) is supported
Whether FP16 (half-precision) is supported
Whether FP64 (double-precision) is supported
The memory bandwidth of the GPU
object
The numerical value of the transfer rate
The unit of the transfer rate value
The memory topology of the host
object
The available memory (usable without swapping)
object
The numerical value of the size
The unit of the size value
The free memory (unused by the OS)
object
The numerical value of the size
The unit of the size value
The total physical memory installed
object
The numerical value of the size
The unit of the size value
The type of physical memory
The DDR generation (e.g., 4 for DDR4, 5 for DDR5). Only applicable when type is DDR.
The disk nodes attached to the deployment target
Disk Node
Describes a physical disk attached to the deployment target.
object
The disk device name (e.g., “/dev/sda”, “/dev/nvme0n1”)
The disk serial number
The total disk size
object
The numerical value of the size
The unit of the size value
The free space available on the disk
object
The numerical value of the size
The unit of the size value
The disk model name
The type of physical disk
The disk throughput (read/write speeds)
object
The sequential read speed
object
The numerical value of the transfer rate
The unit of the transfer rate value
The sequential write speed
object
The numerical value of the transfer rate
The unit of the transfer rate value
The disk IOPS (input/output operations per second)
object
Input operations per time unit (read IOPS)
object
The numerical value of operations
The time unit denominator
Output operations per time unit (write IOPS)
object
The numerical value of operations
The time unit denominator
The network information of the host
object
The hostname of the host
The domain name of the host
The DNS servers configured on the host
The primary MAC address of the host
The network interfaces available on the host
Network Interface
Describes a network interface on the physical host.
object
The IP addresses assigned to this interface
The interface type identifier
The operational status of the interface
The Maximum Transmission Unit (MTU) in bytes
The interface name (e.g., “eth0”, “ens3”)
The display name of the interface
The bandwidth of the interface
object
The current download speed
object
The numerical value of the transfer rate
The unit of the transfer rate value
The current upload speed
object
The numerical value of the transfer rate
The unit of the transfer rate value
The peak download speed observed
object
The numerical value of the transfer rate
The unit of the transfer rate value
The peak upload speed observed
object
The numerical value of the transfer rate
The unit of the transfer rate value
The IP gateways configured on the host
Tags associated with this deployment target for labeling and categorization
Topology Tag
A key-value pair used to label and categorize topology resources such as regions, zones, resource pools, and deployment targets.
object
The unique identifier of the tag
The key of the tag
The value of the tag
The type of the tag (system or user-defined)
An optional description for the tag
The timestamp when the deployment target was registered
The timestamp when the deployment target was last updated
Node Name
The Kubernetes Node name this deployment target projects (node.metadata.name).
Mutable on K8s rename. Used for human-friendly identification and filtering, NOT for
correlation — use node_uid for that.
Node Uid
The Kubernetes Node uid (node.metadata.uid) — durable correlation key (AD-003
§Correlation). Immutable; a deleted-and-recreated Node yields a new uid, which
produces a new DeploymentTarget row rather than resurrecting the old one.
Status
Domain status of the deployment target: one of ready, not_ready,
maintenance, deleted. deleted is the terminal soft-delete state;
findAll listings exclude it by default. maintenance is preferred over
the K8s-specific “cordoned” — see AD-003 §Vocabulary.
Labels
The full Kubernetes Node label map. Powers ResourcePool selector matching.
object
Last Observed At
Last successful reconciler observation — freshness proof for the 5-second SLA.
Zone Id
The zone this deployment target belongs to (FK to topology.zones(id), denormalised onto the row so AIP-160 filters can scope by zone without a JOIN). Populated by the K8s reconciler from the standard topology.kubernetes.io/zone label; empty when the label is absent. Used by compute’s scheduler feasibility check.
A token, which can be sent as page_token to retrieve the next page.
If this field is empty, there are no subsequent pages.
Example
{ "deployment_targets": [ { "os": { "bitness": "OS_BITNESS_UNSPECIFIED" }, "cpu_topology": { "byte_order": "BYTE_ORDER_UNSPECIFIED", "min_frequency": { "unit": "TOPOLOGY_CLOCK_SPEED_UNIT_UNSPECIFIED" }, "max_frequency": { "unit": "TOPOLOGY_CLOCK_SPEED_UNIT_UNSPECIFIED" }, "architecture": "CPU_ARCHITECTURE_UNSPECIFIED" }, "gpu_topology": [ { "base_clock": { "unit": "TOPOLOGY_CLOCK_SPEED_UNIT_UNSPECIFIED" }, "boost_clock": { "unit": "TOPOLOGY_CLOCK_SPEED_UNIT_UNSPECIFIED" }, "vram": { "size": { "unit": "TOPOLOGY_DATA_UNIT_UNSPECIFIED" }, "type": "VRAM_TYPE_UNSPECIFIED", "memory_bus": { "unit": "TOPOLOGY_DATA_UNIT_UNSPECIFIED" } }, "memory_bandwidth": { "unit": "TOPOLOGY_DATA_TRANSFER_RATE_UNIT_UNSPECIFIED" } } ], "memory_topology": { "available_memory": { "unit": "TOPOLOGY_DATA_UNIT_UNSPECIFIED" }, "free_memory": { "unit": "TOPOLOGY_DATA_UNIT_UNSPECIFIED" }, "total_memory": { "unit": "TOPOLOGY_DATA_UNIT_UNSPECIFIED" }, "type": "MEMORY_TYPE_UNSPECIFIED" }, "disks": [ { "size": { "unit": "TOPOLOGY_DATA_UNIT_UNSPECIFIED" }, "free_space": { "unit": "TOPOLOGY_DATA_UNIT_UNSPECIFIED" }, "type": "DISK_TYPE_UNSPECIFIED", "throughput": { "read_speed": { "unit": "TOPOLOGY_DATA_TRANSFER_RATE_UNIT_UNSPECIFIED" }, "write_speed": { "unit": "TOPOLOGY_DATA_TRANSFER_RATE_UNIT_UNSPECIFIED" } }, "iops": { "ips": { "unit": "TOPOLOGY_DURATION_UNIT_UNSPECIFIED" }, "ops": { "unit": "TOPOLOGY_DURATION_UNIT_UNSPECIFIED" } } } ], "network_info": { "interfaces": [ { "status": "NETWORK_STATUS_UNSPECIFIED", "bandwidth": { "download_speed": { "unit": "TOPOLOGY_DATA_TRANSFER_RATE_UNIT_UNSPECIFIED" }, "upload_speed": { "unit": "TOPOLOGY_DATA_TRANSFER_RATE_UNIT_UNSPECIFIED" }, "peak_download_speed": { "unit": "TOPOLOGY_DATA_TRANSFER_RATE_UNIT_UNSPECIFIED" }, "peak_upload_speed": { "unit": "TOPOLOGY_DATA_TRANSFER_RATE_UNIT_UNSPECIFIED" } } } ] }, "tags": [ { "type": "TOPOLOGY_TAG_TYPE_UNSPECIFIED" } ] } ]}default
Section titled “default ”Default error response
The Status type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by gRPC. Each Status message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the API Design Guide.
object
The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
A list of messages that carry the error details. There is a common set of message types for APIs to use.
Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.
object
The type of the serialized message.
Example generated
{ "code": 1, "message": "example", "details": [ { "@type": "example" } ]}