Skip to main content
GET
List a pool's instances
Requires the IAM action compute:GetInstancePool. See COMPUTE permissions for the full list, what each one covers, and an example policy.

Authorizations

Authorization
string
header
required

An OAuth 2.0 bearer token, sent as Authorization: Bearer <token>. This is the recommended way to authenticate.

Get one by exchanging a service account's access key pair at POST /v1/oauth/token with grant_type=client_credentials. It is the standard client-credentials grant, so any OAuth-aware library will obtain and refresh it for you.

Tokens last an hour by default. The same access key pair is separately your AWS SigV4 credential for the S3-compatible object endpoint, which speaks nothing else.

Path Parameters

pool_id
string<uuid>
required
Example:

"8f2a1c3d-4e5b-4a6f-9c0d-1e2f3a4b5c6d"

Query Parameters

crn
string

Exact resource CRN, intersected with all other filters before pagination. A foreign or mismatched CRN returns an empty page; malformed or empty CRNs return 400. Nested attachment lists filter the represented resource, not the binding.

limit
integer
default:20

Maximum number of items to return. A value above the maximum is clamped to it rather than rejected, so a page shorter than the one you asked for is normal — page until meta.has_more is false, not until a page looks short.

Required range: 1 <= x <= 100
marker
string

Opaque pagination cursor. Echo back the meta.marker value from the previous page to fetch the next one; do not construct or parse it. The token's internal form varies by endpoint (a resource ID, a timestamp, …) and is not guaranteed stable across releases.

name
string

Exact, case-sensitive name. Empty values match no named resources. Instance NIC lists match interface names within the instance bindings; multiple interfaces with the same name may match. Floating IPs have no name identity and return an empty list for this filter.

current_state
enum<string>

Filter by where the instances actually are. Where an instance actually is. The transitional states live here, not on desired_state — nobody asks for stopping.

Available options:
pending,
building,
running,
stopping,
stopped,
rebooting,
migrating,
deleting,
deleted,
error,
crashed,
paused,
suspended
flavor
string

Filter by regional flavor reference (UUID, CRN or exact name).

Example:

"a1b2c3d4-e5f6-4789-9abc-def012345678"

image
string

Filter by image reference (UUID, CRN or name; images also accept name:version).

Example:

"550e8400-e29b-41d4-a716-446655440001"

Response

A page of the pool's instances.

instances
object[]
meta
object