Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
List and query compute instances in the active scope
Returns the paginated collection of virtual machine Instances visible in the active
tenant/subscription/project scope (the Instances page route load). This single endpoint also
backs the search/filter/sort/pagination controls (canonical action compute.instance.search_filter_sort
is collapsed into this operation): q matches instance name, fixed IP, or floating IP
("Filter by name or IP…"), status narrows to a lifecycle state (UI quick filters map
Running→ACTIVE, Stopped→STOPPED, Error→ERROR), sort accepts name or createdAt, and
page/pageSize drive the pagination envelope. Each row carries the full Instance read model
(status, powerState, flavor, image, IPs, key pair, tags) needed by the table and row action menus.
Validation: scopeId must reference an accessible scope (UNKNOWN_SCOPE → 404 via ErrNotFound is
not used here — an inaccessible scope yields 403 FORBIDDEN); status must be one of the
InstanceStatus enum values, sort one of [name, createdAt], page>=1, pageSize 1..200 —
violations → 422 VALIDATION_FAILED.
Async & state: Synchronous read; no state change. Clients additionally subscribe to
resource.updated SSE frames with kind=instance and re-fetch this list when one arrives.
Errors: 401 UNAUTHENTICATED when the session is missing/expired; 403 FORBIDDEN when the caller
lacks read access to the scope; 422 VALIDATION_FAILED for malformed query parameters; 500 INTERNAL
on unexpected backend failure.
Idempotency/Concurrency: Safe, cacheable; no idempotency key required.
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
region?stringRestrict the result set to a single region.
^[a-z][a-z0-9-]{1,39}$q?stringFree-text search.
sort?stringField to sort by (entity-specific; defaults to the entity's natural order).
order?stringSort direction.
"asc""asc""desc"page?integer1-based page number.
1 <= value1pageSize?integerItems per page (max 200).
1 <= value <= 20050status?stringFilter instances by lifecycle status (UI quick filters use ACTIVE, STOPPED, ERROR).
"BUILD""ACTIVE""STOPPED""PAUSED""SUSPENDED""RESIZE""VERIFY_RESIZE""RESCUE""ERROR""DELETING"Paginated page of Instances in the active scope matching the query.
application/json- response
data*array<>meta*Pagination envelope metadata. List responses are always { data, meta } — never a naked array.
curl -X GET "https://example.com/scopes/string/compute/instances"{ "data": [ { "subscriptionId": "string", "projectId": "string", "region": "string", "createdAt": "string", "updatedAt": "string", "origin": "portal", "id": "string", "name": "string", "status": "BUILD", "statusReason": "string", "statusReasonCode": "string", "powerState": "RUNNING", "taskState": "string", "flavor": { "id": "string", "name": "string", "family": "string", "restricted": true, "entitled": true, "vcpus": 0, "ramMb": 0, "diskGb": 0, "priceMonthly": { "amount": 0, "currency": "USD" }, "priceHourly": { "amount": 0, "currency": "USD" }, "gpu": { "count": 1, "model": "string" } }, "image": { "id": "string", "name": "string", "os": "string", "osVersion": "string" }, "fixedIp": "string", "floatingIp": "string", "keyPairs": [], "passwordAuth": false, "monitoringEnabled": true, "deletionProtection": true, "tags": [ { "key": "string", "value": "string" } ], "securityGroups": [], "networkInterfaces": [], "availabilityZone": "string", "bootsFromVolume": false, "rootDiskGb": 0, "rootVolumeName": "string", "rootVolumeId": "string" } ], "meta": { "page": 1, "pageSize": 1, "total": 0, "hasNext": true }}