List deployment targets in a zone

This guide shows how to discover deployment targets, the physical hosts in a zone, and narrow the list to the capacity you care about. The list endpoint supports filtering, ordering, and keyset pagination.

Before you begin

• Authentication. Export an API token as $QIBDO_API_TOKEN; the base URL is https://api.qibdo.example.com. See Authenticate a user and manage the session.
• Permissions. Your identity needs permission to read topology resources. See the authorization model.
• Prerequisites. A qibdo-cloud account, and (optionally) a zone id to scope the list to.

Your deployment’s API domain

api.qibdo.example.com is an example host. qibdo runs on your own infrastructure, so the API lives at your deployment’s own domain. Replace it with yours before running these examples.

Console

Coming soon

A step-by-step walkthrough in the qibdo console is on the way. For now, use the REST tab.

CLI

Coming soon

A qibdo CLI walkthrough is on the way. For now, use the REST tab.

REST

List every target

A bare list returns deployment targets sorted by name ascending, up to the default page size of 20 (the maximum is 100):

GET /topology/v1/targets HTTP/1.1
Host: api.qibdo.example.com
Authorization: Bearer $QIBDO_API_TOKEN

The response carries an array of deployment targets and a next_page_token. Soft-deleted targets (those with a deleted status) are excluded by default.

Filter by zone and architecture

Each deployment target carries the zone it sits in and its full CPU description, so you can filter on both. The example below finds x86-64 hosts in one zone and orders them by hostname, requesting a larger page:

curl -G "https://api.qibdo.example.com/topology/v1/targets" \
  -H "Authorization: Bearer $QIBDO_API_TOKEN" \
  --data-urlencode 'filter=zone_id = "8c2d1a90-3f47-4e6b-9a51-0d72f4b8e3c1" AND cpu_topology.architecture = "CPU_ARCHITECTURE_X86_64"' \
  --data-urlencode 'order_by=hostname' \
  --data-urlencode 'page_size=50'

A filter expression is a field name, an operator (=, !=, >, <, <=, >=, or :), and a value (string, number, or boolean). Combine expressions with AND / OR and group them with parentheses. Values are matched exactly and are case-sensitive, so use the token the API returns, as CPU_ARCHITECTURE_X86_64 does above.

Use : rather than = when the field holds a list, and for a substring match on a string. Nested numeric fields compare as numbers, so cpu_topology.cores_per_socket >= 8 also matches 16.

A deployment target considers an enumerated set of fields, including name, hostname, zone_id, and nested paths such as cpu_topology.architecture and disks.size_bytes. The full set for this resource is listed on its page in the topology reference; the language itself is described in Filtering. Nested fields can be filtered but not sorted, which is why order_by above uses hostname.

Page through large result sets

When next_page_token is non-empty, there are more results. Pass it back as page_token to fetch the next page, keeping every other parameter identical to the original call:

curl -G "https://api.qibdo.example.com/topology/v1/targets" \
  -H "Authorization: Bearer $QIBDO_API_TOKEN" \
  --data-urlencode 'filter=zone_id = "8c2d1a90-3f47-4e6b-9a51-0d72f4b8e3c1"' \
  --data-urlencode 'page_size=50' \
  --data-urlencode 'page_token=CggKBnRhcmdldA'

Repeat until the response comes back with an empty next_page_token. List responses intentionally omit a total count: keyset pagination cannot compute one efficiently.

Next steps

• To see how locations, zones, resource pools, and targets relate, see the topology hierarchy.