Docs
Instances

List instances

GET
/v1/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.

Authorization

headerAuthorizationBearer <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

Query Parameters

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.

Itemsitems <= 16
status?array<>

Only instances in these statuses. Without it, every status except terminated, unless idempotencyKey is set.

Itemsitems <= 8
tee?array<>

Only these TEEs.

Itemsitems <= 8
location?array<>

Only these locations.

Itemsitems <= 16
project?array<>

Only instances in these projects. Every org has one project, default, in this version.

Itemsitems <= 16
clusterNode?boolean

true 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.

Itemsitems <= 16
idempotencyKey?string

Only 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.

Match^[!-~]+$
Length1 <= length <= 255
pageSize?integer

The most items to return.

Range1 <= value <= 100
Default50
pageToken?string

The nextPageToken of the previous page, unchanged. Send the same filters with it.

Length1 <= length <= 2048

Header Parameters

Api-Version*string

The 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?string

An 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.

Match^[A-Za-z0-9._:-]+$
Length1 <= length <= 128
Org-Context?string

Admin 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.

Match^org-[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length5 <= length <= 63
Access-Reason?string

Admin 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.

Match^[^\x00-\x1F\x7F]+$
Length10 <= length <= 500

Response Body

A page of instances, newest first.

application/json
  1. response
items*array<>
nextPageToken?NextPageToken

Pass it back as pageToken for the next page. Absent on the last page.

Example Request
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'
Example Response
{  "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"    }  ]}