> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# List a pool's instances
> List full instances scoped to this pool, with the same filters, ordering and pagination as the top-level instance list. The stable replica sequence number is available in instance metadata as `basalt:pool:sequence_num`.
Requires the IAM action **`compute:GetInstancePool`**. See [COMPUTE permissions](/compute/permissions) for the full list, what each one covers, and an example policy.
## OpenAPI
````yaml /api-reference/specs/compute.yaml get /v1/instance-pools/{pool_id}/instances
openapi: 3.0.3
info:
title: Basaltic Compute API
version: 1.0.0
description: |
Virtual machine instances, and the images, flavors, SSH keypairs and
instance pools they are built from. Covers the whole instance lifecycle:
start, stop, reboot, resize and reinstall.
contact:
name: Basaltic Support
email: ping@basaltic.sh
license:
name: Proprietary
url: https://basaltic.sh/terms
servers:
- url: https://compute.{region}.basaltic.sh
description: Regional API endpoint
variables:
region:
default: sa-saopaulo-1
description: Region code
security:
- BearerAuth: []
paths:
/v1/instance-pools/{pool_id}/instances:
parameters:
- name: pool_id
in: path
required: true
schema:
type: string
format: uuid
example: 8f2a1c3d-4e5b-4a6f-9c0d-1e2f3a4b5c6d
get:
tags:
- Compute
summary: List a pool's instances
description: >-
List full instances scoped to this pool, with the same filters, ordering
and pagination as the top-level instance list. The stable replica
sequence number is available in instance metadata as
`basalt:pool:sequence_num`.
operationId: listPoolInstances
parameters:
- $ref: '#/components/parameters/ComputeCRNFilter'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Marker'
- $ref: '#/components/parameters/ComputeNameFilter'
- name: current_state
in: query
description: Filter by where the instances actually are.
schema:
$ref: '#/components/schemas/CurrentState'
- name: flavor
in: query
description: Filter by regional flavor reference (UUID, CRN or exact name).
schema:
type: string
example: a1b2c3d4-e5f6-4789-9abc-def012345678
- name: image
in: query
description: >-
Filter by image reference (UUID, CRN or name; images also accept
name:version).
schema:
type: string
example: 550e8400-e29b-41d4-a716-446655440001
responses:
'200':
description: A page of the pool's instances.
content:
application/json:
schema:
$ref: '#/components/schemas/InstanceListResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
security:
- BearerAuth: []
components:
parameters:
ComputeCRNFilter:
name: crn
in: query
description: >-
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.
schema:
type: string
Limit:
name: limit
in: query
description: >-
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: false
schema:
type: integer
minimum: 1
maximum: 100
default: 20
example: 20
Marker:
name: marker
in: query
description: >-
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.
required: false
schema:
type: string
example: 550e8400-e29b-41d4-a716-446655440000
ComputeNameFilter:
name: name
in: query
description: >-
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.
schema:
type: string
schemas:
CurrentState:
type: string
description: |
Where an instance actually is. The transitional states live here,
not on desired_state — nobody asks for `stopping`.
enum:
- pending
- building
- running
- stopping
- stopped
- rebooting
- migrating
- deleting
- deleted
- error
- crashed
- paused
- suspended
InstanceListResponse:
type: object
properties:
instances:
type: array
items:
$ref: '#/components/schemas/Instance'
meta:
$ref: '#/components/schemas/PaginationMeta'
Instance:
type: object
required:
- faults
properties:
id:
type: string
format: uuid
readOnly: true
example: 550e8400-e29b-41d4-a716-446655440000
crn:
type: string
readOnly: true
description: Cloud Resource Name
example: crn:compute:sa-saopaulo-1:my-account:instance/web-01
name:
description: >-
Resource names must not start with the literal crn: prefix or be
UUIDs (canonical, compact, braced, or urn:uuid: forms, in either
case).
type: string
example: web-server-01
description:
type: string
example: Primary web server
task_state:
type: string
nullable: true
description: In-flight transition, if any; null when settled.
example: null
flavor:
allOf:
- $ref: '#/components/schemas/Flavor'
description: >-
Resolved flavor (compute size) the instance runs on. Omitted if the
referenced flavor row has been retired.
image:
allOf:
- $ref: '#/components/schemas/Image'
description: >-
Resolved source image the instance booted from. Omitted for a
volume-only boot or if the referenced image row is gone.
keypairs:
type: array
description: >-
SSH keypairs baked into the instance at launch. These are embedded —
unlike attached volumes, NICs, and security groups, which each have
their own list endpoint and so are not duplicated here.
items:
$ref: '#/components/schemas/Keypair'
user_data:
type: string
description: Base64-encoded cloud-init user-data supplied at launch.
iam_role:
allOf:
- $ref: '#/components/schemas/InstanceRole'
description: >-
Summary of the attached IAM role, visible with instance read access
without iam:GetRole. Omitted when no role is attached, the role was
deleted, or it belongs to another account. Sensitive role fields
remain available only through the IAM API.
metadata:
$ref: '#/components/schemas/Metadata'
tags:
$ref: '#/components/schemas/Tags'
faults:
type: array
description: >-
Active faults ordered by last_at descending, then internal history
id descending for a stable tie-breaker. Healthy resources return [].
items:
$ref: '#/components/schemas/Fault'
created_at:
type: string
format: date-time
readOnly: true
example: '2024-01-15T10:30:00Z'
updated_at:
type: string
format: date-time
readOnly: true
example: '2024-01-15T10:30:00Z'
launched_at:
type: string
format: date-time
readOnly: true
nullable: true
example: '2026-01-15T09:31:12Z'
terminated_at:
type: string
format: date-time
readOnly: true
nullable: true
example: null
desired_state:
type: string
enum:
- running
- stopped
- deleted
example: running
description: |
What was asked for. Only three values, because there are only three
things you can ask an instance to be: Create/Start/Reboot ask for
running, Stop for stopped, Delete for deleted.
current_state:
$ref: '#/components/schemas/CurrentState'
example: running
description: |
Where the instance actually is. Read this one to answer "is it up" —
the transitional states live here, not on desired_state, because
nobody asks for `stopping`.
desired_state=running with current_state=stopped is an instance that
was asked to start and has not come up yet.
PaginationMeta:
type: object
properties:
total:
type: integer
description: Total number of items
example: 150
limit:
type: integer
description: Number of items per page
example: 20
marker:
type: string
description: >-
Opaque cursor for the next page. Pass it back as the `marker` query
parameter; treat it as a token, not a value to parse.
example: 550e8400-e29b-41d4-a716-446655440000
has_more:
type: boolean
description: Whether there are more items
example: true
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
- request_id
properties:
code:
type: string
description: Error code identifying the type of error
example: INVALID_INPUT
message:
type: string
description: Human-readable error message
example: Invalid request parameters
request_id:
type: string
format: uuid
description: Request ID for debugging
example: 550e8400-e29b-41d4-a716-446655440000
Flavor:
type: object
description: >-
A compute size (vCPU + RAM). A flavor carries no disk size — the boot
disk is a customer volume sized at launch, floored by the image's
min_disk_gb.
properties:
id:
type: string
format: uuid
readOnly: true
example: 550e8400-e29b-41d4-a716-446655440000
crn:
type: string
readOnly: true
description: Cloud Resource Name
example: crn:compute:sa-saopaulo-1:platform:flavor/standard-2
name:
description: >-
Resource names must not start with the literal crn: prefix or be
UUIDs (canonical, compact, braced, or urn:uuid: forms, in either
case).
type: string
example: m1.medium
description:
type: string
example: Medium instance with 2 vCPUs and 4GB RAM
vcpus:
type: integer
description: Number of virtual CPUs
example: 2
ram_mb:
type: integer
description: RAM in MB
example: 4096
class:
type: string
description: >-
Host-pool routing. "shared" oversubscribes CPU for higher density;
"dedicated" pins each vCPU 1:1 to a physical core.
enum:
- shared
- dedicated
example: shared
family:
type: string
description: >-
Which product can book the flavor. "general" flavors are for regular
instances and instance pools; "loadbalancer" and "database" flavors
are reserved for the managed products (their nodes are platform-
operated and priced accordingly) and cannot be used for regular
instances.
enum:
- general
- loadbalancer
- database
example: general
status:
type: string
enum:
- active
- disabled
example: active
created_at:
type: string
format: date-time
readOnly: true
updated_at:
type: string
format: date-time
readOnly: true
Image:
type: object
properties:
id:
type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
crn:
type: string
example: >-
crn:compute:sa-saopaulo-1:my-account:image/ubuntu-24.04/architecture/amd64/version/20260901
name:
description: >-
Resource names must not start with the literal crn: prefix or be
UUIDs (canonical, compact, braced, or urn:uuid: forms, in either
case).
type: string
example: ubuntu-24.04
description:
type: string
example: Ubuntu 24.04 LTS (Noble Numbat)
os:
type: string
example: ubuntu
os_version:
type: string
example: '24.04'
architecture:
type: string
example: amd64
version:
type: string
description: |
The build's identity within its name. Unique there: a name is a
movable tag, so it can't also be what tells two builds apart.
Stamped as a UTC timestamp when the uploader didn't choose one.
example: '20260807'
is_current:
type: boolean
description: |
Whether this is the version resolve-by-name returns for its
(name, architecture) — i.e. the name's current tag target.
example: true
eol_date:
type: string
format: date
description: |
The day this image's OS release stops receiving free security
updates for a default install. Absent when nobody has recorded
one — which means unknown, not "supported indefinitely".
Platform images are withdrawn from the catalog a grace period
after this date. They stay bootable by id until then, and the
date is published well ahead of it so you can plan the move.
example: '2026-08-31'
size_bytes:
type: integer
format: int64
example: 2361393152
min_disk_gb:
type: integer
minimum: 0
maximum: 16384
example: 10
min_ram_mb:
type: integer
minimum: 0
example: 1024
status:
type: string
enum:
- pending
- importing
- active
- error
- deleting
- withdrawn
description: >-
Error exactly while an active error fault exists; import and
deletion progress remain independently retryable.
example: active
withdrawal_reason:
type: string
description: >
Why this image was withdrawn. Present for withdrawn images,
including those with an independent error fault:
end_of_life for platform release withdrawal (see eol_date), or
legacy for a migrated withdrawal whose original reason is unknown.
Withdrawn images retain their data but cannot be launched.
example: end_of_life
faults:
type: array
readOnly: true
description: >-
Active faults, newest first. Empty for a healthy image. Error faults
set status to error without disabling an eligible import or cleanup
retry.
items:
$ref: '#/components/schemas/Fault'
tags:
$ref: '#/components/schemas/Tags'
attributes:
type: object
additionalProperties:
type: string
created_at:
type: string
format: date-time
example: '2026-01-15T09:30:00Z'
updated_at:
type: string
format: date-time
example: '2026-01-15T09:30:00Z'
required:
- id
- crn
- name
- version
- architecture
- status
- faults
- created_at
- updated_at
Keypair:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
example: 550e8400-e29b-41d4-a716-446655440000
crn:
type: string
readOnly: true
description: Cloud Resource Name
example: crn:compute:sa-saopaulo-1:my-account:keypair/my-keypair
name:
description: >-
Resource names must not start with the literal crn: prefix or be
UUIDs (canonical, compact, braced, or urn:uuid: forms, in either
case).
type: string
example: my-keypair
public_key:
type: string
description: SSH public key
example: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB...
fingerprint:
type: string
readOnly: true
example: 2e:f8:7e:a7:d9:85:c6:c9:44:89:6a:4c:56:7e:98:42
tags:
$ref: '#/components/schemas/Tags'
created_at:
type: string
format: date-time
readOnly: true
InstanceRole:
type: object
required:
- id
- crn
- name
properties:
id:
type: string
format: uuid
example: b2c3d4e5-f6a7-8901-2345-67890abcdef1
crn:
type: string
description: Account-scoped role identity, as used in policy documents.
example: crn:iam::my-account:role/deploy
name:
type: string
description: Immutable role name.
example: deploy
Metadata:
type: object
additionalProperties:
type: string
example:
environment: production
team: backend
Tags:
type: object
additionalProperties:
type: string
example:
environment: production
team: backend
Fault:
type: object
required:
- code
- severity
- message
- details
- first_at
- last_at
- occurrences
properties:
code:
type: string
description: Stable machine-readable code owned by the reporting operation.
example: BACKUP_FAILED
severity:
type: string
enum:
- error
- warning
message:
type: string
example: Backup upload failed.
details:
type: object
nullable: true
additionalProperties: true
description: Structured context; legacy strings are preserved in legacy_text.
first_at:
type: string
format: date-time
description: First observation in this active occurrence series.
last_at:
type: string
format: date-time
description: Latest observation in this active occurrence series.
occurrences:
type: integer
minimum: 1
example: 1
responses:
BadRequest:
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: INVALID_INPUT
message: Invalid request parameters
request_id: 550e8400-e29b-41d4-a716-446655440000
Unauthorized:
description: Authentication required or token invalid
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: UNAUTHORIZED
message: Authentication required
request_id: 550e8400-e29b-41d4-a716-446655440000
Forbidden:
description: Insufficient permissions
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: ACCESS_DENIED
message: You don't have permission to perform this action
request_id: 550e8400-e29b-41d4-a716-446655440000
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: NOT_FOUND
message: Resource not found
request_id: 550e8400-e29b-41d4-a716-446655440000
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: |
An OAuth 2.0 bearer token, sent as `Authorization: Bearer `.
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.
```
curl -s -u "$KEY_ID:$SECRET" -d grant_type=client_credentials \
https://iam.basaltic.sh/v1/oauth/token
```
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.
````