Docs
Instances

Get an instance

GET
/v1/instances/{id}

Returns the instance, including a terminated tombstone for 90 days after it ended.

With waitFor, the call holds for up to timeoutSeconds until the instance reaches the target, and returns early when it reaches failed, stopped, terminated or unknown. It returns 200 with the current state either way, so check status and conditions in the response. To wait longer, call again; while the instance is unknown, pause between calls.

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

Path Parameters

id*string

The instance id.

Match^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length1 <= length <= 63

Query Parameters

waitFor?string

Hold the call until the instance reaches this target: running, reachable (running with condition Reachable True) or terminated. Without it, the call returns at once.

timeoutSeconds?integer

How long to hold the call with waitFor, in seconds. Ignored without waitFor.

Range1 <= value <= 60
Default30

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

The instance.

application/json
  1. response

A confidential virtual machine.

id*InstanceId

Opaque. Starts with i-, is a lowercase DNS label of at most 63 characters, and may change length or form within those rules.

Match^i-[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Lengthlength <= 63
name?string

The instance's name, from its create or its latest rename. Absent if neither gave one.

Lengthlength <= 63
project*ProjectName

The project the instance belongs to. Every org has one project, default, in this version.

Match^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length1 <= length <= 63
status*InstanceStatus

Only when status is unknown, the status before the host stopped reporting.

statusReason?

Why the instance is in its status. Absent when there is nothing to add.

statusChangedAt*string

When status last changed.

Formatdate-time
lastKnownStatus?InstanceStatus

Only when status is unknown, the status before the host stopped reporting.

conditions*array<>

Signals about the instance, Kubernetes style. A new instance has none. No condition ever says whether the instance can be trusted: verify that yourself.

tee*Tee

The trusted execution environment. Open set; accept values not listed.

location*LocationId

A location id from GET /v1/locations, such as us-west-1.

Match^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length1 <= length <= 63
size*SizeId

A size id from GET /v1/sizes, such as s1.4x. Read ids from that list; do not build them.

Match^[a-z0-9]([-.a-z0-9]*[a-z0-9])?$
Length1 <= length <= 63
compute*

The resolved size.

image*

The image version and artifact the instance boots.

container?

The OCI image the instance runs as its only workload, present when the create's image named one. The instance's image pulls it by digest at every boot and runs it on the instance's network.

disks*array<>

The writable disks, in the order the create listed them.

network*

How the instance is reached.

readiness?

The guest ports Reachable waits on, as the create named them or the image's default.

endpoints*array<>

Where to reach the instance: one entry per ingress rule and, when the image's attestationPublic is true, one named attest for its attestation service, on the public IPv4 address, and the same again on the instance's IPv6 address on the guest's own ports where the location routes IPv6. A rule on port 443 has one more for each of the instance's hostnames, on the name's port 443. An endpoint never changes while the instance holds its address: the platform's ports on the shared address and its names for the instance's life, and an address attached to it until it is detached. Those of the create are assigned when it is accepted, so the 202 response carries them. Empty once the instance is terminated.

privateAddress?string

The instance's address on its private network. Present only with network.privateNetwork, from the moment the create is accepted until the instance is terminated.

Formatipv4
boot*

Every boot is a fresh measured launch, and every disk whose encryption is guest starts it empty, under a new key. If you hold a session to an attested key, attest again when count moves.

access?

The SSH keys written to the launch disk, in order, each normalised as the create describes and without its line feed: the pubkey file is these strings, each followed by a line feed.

trust?

The launch key written to the launch disk, exactly as the create gave it, and the format of the launch document. The document itself is never returned.

attestation*

What you need to verify the instance yourself. The API never says whether an instance can be trusted.

reservation?ReservationId

The GPU reservation the instance draws on. Only for GPU sizes.

Match^r-[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Lengthlength <= 63
purchaseOption?PurchaseOption

How the instance was bought: on-demand, reservation or spot. A spot instance runs on GPUs that no active reservation holds, and is stopped, never deleted, when something of higher priority needs them (the Spot GPUs rules above).

maintenanceEventId?string

The instance's open maintenance event, if it has one: GET /v1/instances/{id}/maintenance returns it.

preemptAt?string

Only while the reason is preempting: when the platform will stop the instance, 60 seconds after its guest was asked to shut down.

Formatdate-time
terminationAt?string

When the platform will delete the instance: the end of its reservation. Only for instances in a reservation.

Formatdate-time
expiresAt?string

When the platform will delete the instance, as a delete request would, leaving a tombstone with reason expired. Absent when the instance does not expire; every instance an agent credential creates has one. POST /v1/instances/{id}/extend moves it later.

Formatdate-time
gpuMetrics?boolean

Whether Confidential Cloud reads the GPU metrics this instance's guest serves on TCP 9400, for your org's metrics and Instances dashboard. On for an image whose launch.gpuMetrics is true unless its create turned it off, and off for any other image; fixed for the instance's life, and in its measured pubkey file when on. Only for sizes with GPUs, and absent for the others.

placement?
role?string

Only on a node of a managed Kubernetes cluster, which the cluster's controller created and only the cluster replaces or deletes: worker for a node of a node pool, cds for a replica of the cluster's CDS. Open set; accept values not listed. The controller's create stated it and it never changes. No label says this: role is absent on an instance you created, whatever its labels.

cluster?ClusterId

The managed cluster the instance is a node of, which its controller's create recorded. Only with role. No label says this.

Match^cl-[0-9a-f]{16}$
nodePool?NodePoolName

The node pool the instance is a node of. Only with the role worker.

Match^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length1 <= length <= 40
cdsReplica?integer

Which replica of its cluster's CDS the instance is, from 0. Only with the role cds.

Range0 <= value <= 99
labels*

Labels. May include keys with a reserved prefix, such as cloud.confidential.ai/, which the platform sets.

createdAt*string

When the create was accepted.

Formatdate-time
Example Request
curl -X GET 'https://api.cloud.confidential.ai/v1/instances/i-7k2m9q4x1bfa?waitFor=reachable&timeoutSeconds=60' \  -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
{  "id": "i-7k2m9q4x1bfa",  "name": "poc-0",  "project": "default",  "status": "running",  "statusChangedAt": "2026-10-22T17:03:31Z",  "conditions": [    {      "type": "Reachable",      "status": "True",      "reason": "TcpDialSucceeded",      "message": "The guest's wait ports accepted connections from inside our network.",      "lastTransitionTime": "2026-10-22T17:03:52Z"    }  ],  "tee": "tdx",  "location": "us-west-1",  "size": "s1.4x",  "compute": {    "vcpus": 4,    "memoryGiB": 16  },  "image": {    "family": "confos-cpu",    "version": "2026.10.2",    "launch": "general-purpose/1",    "digest": "sha256:8c780b3655fc55a663ed38174927e149157c6d2bedf81b9ce60a0a6d8ec33947"  },  "disks": [    {      "name": "data",      "type": "scratch",      "sizeGiB": 20,      "encryption": "guest"    },    {      "name": "user-data",      "type": "scratch",      "sizeGiB": 40,      "encryption": "none"    }  ],  "network": {    "publicIp": "shared",    "ingress": [      {        "name": "ssh",        "port": 22      },      {        "name": "https",        "port": 443      }    ],    "hostnames": [      "i-7k2m9q4x1bfa.hil1.apps.example.com"    ]  },  "endpoints": [    {      "name": "ssh",      "host": "203.0.113.10",      "ipVersion": "ipv4",      "port": 20022    },    {      "name": "https",      "host": "203.0.113.10",      "ipVersion": "ipv4",      "port": 20443    },    {      "name": "https",      "host": "i-7k2m9q4x1bfa.hil1.apps.example.com",      "port": 443    },    {      "name": "attest",      "host": "203.0.113.10",      "ipVersion": "ipv4",      "port": 29840    }  ],  "boot": {    "count": 1,    "startedAt": "2026-10-22T17:03:31Z"  },  "access": {    "sshKeys": [      "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHwcz1ZWdpesQj0g1D1Cdceg8JdZMFFgKA+foafqkkUg alice@example.com"    ]  },  "attestation": {    "endpoint": "attest",    "referenceManifest": {      "uri": "https://measurements.example/confos-cpu/2026.10.2/tdx/manifest.json",      "digest": "sha256:472d2826575f5b45c0b463738780a3200de086f98737e7b5bf5298b02a475308",      "logEntry": "rekor:1293847"    },    "launchBinding": {      "file": "pubkey",      "sha256": "e52aa028552af775a3aa80566fcf1ef2f9210870656859d03111f2359e8cd5f7",      "sha384": "00cc08934f0fadc537830d00499abdec1da4271756307f822a8ee1cae83d30b0b3b8b4442bc7215e67e2d0751bd54ae5"    }  },  "placement": {    "group": "poc",    "policy": "colocate"  },  "labels": {    "purpose": "poc"  },  "createdAt": "2026-10-22T17:02:11Z"}

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.

Rename an instance PATCH

Changes the instance's name and returns the instance. A body without `name` or `gpuMetrics` returns `400 invalid_request`. Nothing else about the instance changes: its id, its hostnames, which are named after its id, its endpoints and its guest stay as they are. A value the instance already has changes nothing, so sending the same request again is safe. A name that another live instance of the project has returns `409 name_conflict`, with `details.conflictingNames` naming it. An instance that is `terminating` or `terminated` cannot be changed: the call returns `409 invalid_state`. `gpuMetrics` is fixed at create, since the instance's measured launch file holds it (Metrics above): a body may repeat the instance's value, and any other value returns `400 invalid_request` with a `not_allowed` violation at `/gpuMetrics`.