List instances
Lists the org's instances, newest first. terminated tombstones are
left out unless status includes terminated or idempotencyKey is
set. Filters combine with AND, and repeated values of one filter
combine with OR, except label, where every selector must match.
AuthorizationBearer <cc_...>An API key of your org, sent as Authorization: Bearer cc_.... Keys
start with cc_ and are otherwise opaque. Treat a key as a password:
anyone holding it can act with its scopes until it expires or is
revoked. Each operation's security requirement lists the scopes it
needs; an empty list means any valid key. The MCP server at /mcp
accepts agent keys and no other kind.
Scope: instances:read
label?array<>Only instances whose labels match. Each value is key=value, which
matches that value, or key, which matches any value. Repeat the
parameter to require every selector, as in
label=c8s-cluster=c1&label=c8s-role.
items <= 16status?array<>Only instances in these statuses. Without it, every status except
terminated, unless idempotencyKey is set.
items <= 8tee?array<>Only these TEEs.
items <= 8location?array<>Only these locations.
items <= 16project?array<>Only instances in these projects. Every org has one project, default, in this version.
items <= 16clusterNode?booleantrue for only the nodes of managed Kubernetes clusters, the
instances with a role; false for only the others.
reservation?array<>Only instances in these GPU reservations.
items <= 16idempotencyKey?stringOnly the instances that the create with this Idempotency-Key
created, terminated tombstones included unless status leaves them
out, so a client that lost a create's response can find what it made.
^[!-~]+$1 <= length <= 255pageSize?integerThe most items to return.
1 <= value <= 10050pageToken?stringThe nextPageToken of the previous page, unchanged. Send the same
filters with it.
1 <= length <= 2048Api-Version*stringThe API version the request is written against. This document
describes 2026-10-15. A missing header returns
400 api_version_required, and a version the API does not serve
returns 400 unsupported_api_version.
X-Correlation-ID?stringAn id of your own for this request, or for a group of requests, to
find them in our logs and yours. Logged with the request and returned
unchanged in X-Correlation-ID. The request id itself is always the
API's own, in X-Request-ID.
^[A-Za-z0-9._:-]+$1 <= length <= 128Org-Context?stringAdmin keys only: the id of the org to act in. Required with an admin
key, together with Access-Reason; with any other credential it
returns 400 invalid_request. Every request that carries it is
recorded in that org's operator-access log.
^org-[a-z0-9]([-a-z0-9]*[a-z0-9])?$5 <= length <= 63Access-Reason?stringAdmin keys only: why the operator is acting in the org, such as a
support ticket. Required with Org-Context. Recorded, verbatim, in
the org's operator-access log.
^[^\x00-\x1F\x7F]+$10 <= length <= 500A page of instances, newest first.
application/json- response
items*array<>nextPageToken?NextPageTokenPass it back as pageToken for the next page. Absent on the last page.
curl -X GET 'https://api.cloud.confidential.ai/v1/instances?label=c8s-cluster%3Dc1&status=running&tee=tdx&location=us-west-1&project=default&clusterNode=false&reservation=r-5mf2k9x3qp&idempotencyKey=0b9d6c1e-5f8a-4c2e-9a51-2f7e0c3d4b18&pageSize=50&pageToken=eyJjIjoiMjAyNi0xMC0yMlQxNzowMjoxMVoiLCJpIjoiaS03azJtOXE0eDFiZmEifQ' \ -H 'Api-Version: 2026-10-15' \ -H 'X-Correlation-ID: rollout-2026-10-22' \ -H 'Access-Reason: Support ticket 4821: customer asked why i-6d3f9h2k8mzr failed'{ "items": [ { "id": "i-9p4t1v7z3kqm", "name": "c1-server", "project": "default", "status": "running", "statusChangedAt": "2026-10-22T18:10:29Z", "conditions": [ { "type": "Reachable", "status": "True", "reason": "TcpDialSucceeded", "message": "The guest's wait ports accepted connections from inside our network.", "lastTransitionTime": "2026-10-22T18:10:58Z" } ], "tee": "tdx", "location": "us-west-1", "size": "c1.4x", "compute": { "vcpus": 4, "memoryGiB": 8 }, "image": { "family": "c8s-node", "version": "2026.10.1", "launch": "c8s-node/1", "digest": "sha256:982a8305d97e901e472678751f00d86c5db63baf65386d815d00e0d6c5487ba1" }, "disks": [ { "name": "data", "type": "scratch", "sizeGiB": 64, "encryption": "guest" } ], "network": { "publicIp": "shared", "ingress": [ { "name": "router", "port": 443 }, { "name": "release", "port": 8443 }, { "name": "api", "port": 6443 } ] }, "readiness": { "tcpPorts": [ 9345, 6443 ] }, "endpoints": [ { "name": "router", "host": "203.0.113.10", "ipVersion": "ipv4", "port": 20445 }, { "name": "release", "host": "203.0.113.10", "ipVersion": "ipv4", "port": 20446 }, { "name": "api", "host": "203.0.113.10", "ipVersion": "ipv4", "port": 20447 } ], "boot": { "count": 1, "startedAt": "2026-10-22T18:10:29Z" }, "trust": { "launchKey": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEABhAh4OfmU+xIc5Hl6CtY8bM5Ws1mD1hqvY5qqLRCwpQ=\n-----END PUBLIC KEY-----\n", "initData": { "format": "c8s-launch/v1" } }, "attestation": { "referenceManifest": { "uri": "https://measurements.example/c8s-node/2026.10.1/tdx/manifest.json", "digest": "sha256:f39fd2c06953c22cc4f5c65815dc4aa5bc2dc24796969c5e8e5586c4e75761dd", "logEntry": "rekor:1293911" }, "launchBinding": { "file": "pubkey", "sha256": "e127c91f61148be187908f432ce47762e6cf20eb2bd9a0fec246c9c804ee8b36", "sha384": "ba4fd603fce97c3084816ceb2f88f858b0a086c438ef529e7dc70a1f9bc9cac90ca5d628ca8758195b6d85593ac88933" } }, "labels": { "c8s-cluster": "c1", "c8s-role": "server" }, "createdAt": "2026-10-22T18:09:55Z" } ]}Limits and errors
Rate limits, quotas, idempotent retries, pagination, versioning and every error code.
Create instances POST
Creates 1 to 16 instances of one shape in one location. Billable from first boot. Requires `Idempotency-Key`. Admission is all or nothing: the org's quotas, the caller's explicitly configured limits and host capacity are checked for the whole `count`, and on success every instance is placed, addressed and returned in status `provisioning` before the response is sent. After that each instance boots, or fails, on its own. Instances of one request share a location and a TEE, and with `placement.policy: colocate` a host. The image's launch contract (`GET /v1/images`) decides which disks the request must list, whether it takes `access.sshKeys` or `trust.launchKey` with `trust.initData`, and which sizes it runs on. A GPU size needs `reservation`, unless `purchaseOption` is `spot`, and a CPU size must not have one. Something the image or another field requires but the request leaves out is `400 invalid_request`; values that are each valid but do not go together are `422 unsupported_combination` (see Errors). Disks whose `encryption` is `guest` read as empty after every boot, and every disk is destroyed on delete.