Docs
Reservations

List reservations

GET
/v1/reservations

Lists the org's GPU reservations, newest first, in every status.

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: reservations:read

Query Parameters

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 reservations, 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/reservations?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": "r-5mf2k9x3qp",      "displayName": "November training run",      "status": "active",      "statusChangedAt": "2026-11-02T00:00:00Z",      "offering": "ro-3hx8k2",      "location": "us-west-1",      "tee": "tdx",      "gpu": {        "model": "b300",        "count": 8      },      "start": "2026-11-02T00:00:00Z",      "end": "2026-12-02T00:00:00Z",      "term": "P30D",      "price": {        "currency": "USD",        "perGpuHour": "7.00",        "total": "40320.00"      },      "gpusInUse": 2,      "requestedBy": {        "userId": "user_01J8ZQ4X3N2M5K7P9R6T",        "agent": false      },      "createdAt": "2026-10-22T17:40:00Z"    }  ]}

Find GPU reservation offerings GET

Returns up to six priced offerings for whole GPUs of one model, for a term of at least seven days, starting as near to `start` as capacity allows. Each offering's price holds until its `expiresAt`. An empty list means nothing fits.

Request a GPU reservation POST

Requests the GPUs in an offering for its term. Requires `Idempotency-Key`. Returns `202` with the reservation. A request made with an agent credential starts `awaiting_approval`, with an `approval` whose `url` an owner of the org opens in our console to approve or decline it within 72 hours: hand that link to a person. Approved, it becomes `requested`; declined, or undecided by `approval.expiresAt`, it becomes `declined`. Any other request starts `requested`. A `requested` reservation is invoiced for its total, in `invoice`: emailed to your org's billing email and due 10 days after the request or at the reservation's start, whichever is first. A card on file is never charged for it. Paying it confirms the reservation; one still unpaid at `invoice.dueAt` is declined. Once `confirmed`, a reservation cannot be withdrawn or refunded. You can withdraw a request with `DELETE` until it is confirmed, which voids its invoice. When the window opens the reservation becomes `active`, and `POST /v1/instances` with `reservation` and a GPU size launches instances against it: any size of its GPU model with `reservation` in `purchaseOptions`, so its GPUs are split across sizes as you like. At the end of the term the platform deletes those instances.