List nodes in a zone

This guide shows how to discover nodes, 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.

List every node

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

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

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

Filter by zone and architecture

Each node 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/nodes" \
  -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.

Whether capitalisation matters depends on the operator. = and the relational operators are exact, so use the token the API returns, as CPU_ARCHITECTURE_X86_64 does above. For a field with a fixed set of values like this one, the token itself resolves in any case, and a value outside the set is rejected rather than returning an empty page.

Use : rather than = when the field holds a list, and for a substring match on a string. A substring match ignores capitalisation, so name : "gpu" and name : "GPU" return the same nodes. Nested numeric fields compare as numbers, so cpu_topology.cores_per_socket >= 8 also matches 16.

A node 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/nodes" \
  -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=$NEXT_PAGE_TOKEN"

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, node pools, and nodes relate, see the topology hierarchy.