---
title: "Reserve a GPU"
method: POST
path: "/reservations"
tags: ["Reservations"]
---

# Reserve a GPU

`POST /reservations`

## Request

- Base URL: `https://gpucloud.ca/api`
- URL: `https://gpucloud.ca/api/reservations`
- Auth: HTTP bearer

Reserve a GPU machine that is out of stock: GPU Cloud launches the server automatically as soon as it is back, before other customers (first come, first served per machine). A saved credit card is required (402 with error RESERVATION_CARD_REQUIRED and accountAction PAYMENT_REQUIRED carrying the card link), and the explicit authorization (consent). The automatic reload is not required: the answer carries onFundsExhausted, hibernationThresholdCad and, when the reload is off, autoReloadWarning. Nothing is charged when reserving; at launch, only the amount missing (first hour plus the hibernation threshold) is charged to the saved card.

## Request body

- CreateReservationRequest
  - `productId` string, required: Exact GPU machine (model and size), e.g. gpu-h100-x8.
  - `sshKeyId` string, required
  - `maxHourlyCad` number, required: Highest hourly price accepted (CAD): at least the current price, at most 5 times it.
  - `validityDays` integer
  - `acceptAlternative` boolean: Launch an equivalent machine (same usage, at least the same GPU memory, never spot) when the exact one is not in stock.
  - `name` string: Server name: letters, digits, space, dot, dash, underscore (63 at most).
  - `templateId` string
  - `templateModel` string
  - `consent` true, required: The user explicitly agreed: "I authorize GPU Cloud to launch this server as soon as it is available, to charge my saved card the amount needed if my balance is not enough, then to bill it by the hour under the terms."
  - `consentVersion` string, required
  - `consentLang` 'fr' | 'en'
  - `onFundsExhausted` 'HIBERNATE' | 'DELETE': What happens to this hourly server when the balance reaches its threshold and no automatic reload brings it back. HIBERNATE: hibernated (its GPU place is kept, hourly hibernation fee), restarted as soon as the balance is back above the threshold, deleted after 12 hours without credit. DELETE: deleted at once, no hibernation fee, data lost. Machines that cannot be hibernated (spot) are always DELETE. Any other value: 400.

## Response `201`

The reservation

- object
  - `reservation` Reservation: A GPU reservation: GPU Cloud launches the server automatically as soon as the machine is back in stock (first come, first served per machine).
    - `id` string
    - `productId` string: Exact machine reserved (model and size).
    - `productName` string
    - `status` 'ACTIVE' | 'PROCESSING' | 'FULFILLED' | 'PAYMENT_FAILED' | 'EXPIRED' | 'CANCELLED'
    - `maxHourlyCad` number: Highest hourly price accepted (CAD). Above it at launch time, the reservation waits.
    - `acceptAlternative` boolean
    - `templateId` string, nullable
    - `templateModel` string, nullable
    - `name` string, nullable
    - `expiresAt` string, date-time
    - `createdAt` string, date-time
    - `queuePosition` integer, nullable: Place in the queue of this machine (1 = next) while waiting.
    - `waitingReason` string, nullable: PRICE_ABOVE_MAX, BUDGET_LIMIT_REACHED, KEY_CAP_REACHED, SETUP_REQUIRED or SSH_KEY_MISSING while it waits for that reason.
    - `cancelRequested` boolean
    - `serverId` string, nullable: Server launched for it (FULFILLED).
    - `fulfilledProductId` string, nullable
    - `fulfilledAt` string, date-time, nullable
    - `source` 'console' | 'api' | 'mcp'
    - `onFundsExhausted` 'HIBERNATE' | 'DELETE': Action at the threshold of the server this reservation launches.
  - `onFundsExhausted` 'HIBERNATE' | 'DELETE'
  - `allowedOnFundsExhausted` string[]
  - `hibernationThresholdCad` number
  - `autoReloadEnabled` boolean
  - `onFundsExhaustedNote` string
  - `autoReloadWarning` AutoReloadWarning, nullable: Present only when the automatic reload is OFF: show the message to the user. Never a payment link.
    - `code` 'AUTO_RELOAD_OFF'
    - `action` 'HIBERNATE' | 'DELETE'
    - `thresholdCad` number: Threshold of the server (CAD): the larger of 3 CAD and 2 hours of its rate.
    - `message` string
    - `autoReloadSettingsUrl` string, uri: Console page where the automatic reload is turned on.

## Other responses

- `400`: Invalid request
- `401`: No API key (accountAction.code NO_API_KEY) or an invalid, expired, revoked or read only key on a write (INVALID_API_KEY). Provide a valid API key as `Authorization: Bearer <key>`; accountAction gives the links to create an account and a key.
- `402`: Payment required (accountAction.code PAYMENT_REQUIRED: not enough credit, no saved card or a declined card) or a budget cap reached (BUDGET_CAP_REACHED: account or server budget limit, nothing charged). accountAction.balanceCad gives the balance and, when a server is concerned, accountAction.hibernationThresholdCad its hibernation threshold (a server is hibernated when the balance reaches it, kept 12 hours at most, then deleted; it restarts as soon as the balance is above it). Add your card and credits at accountAction.action.url (or raise the cap), then send the same request again.
- `404`: Resource not found
- `409`: Too many reservations waiting (5 at most)
- `429`: Rate limit exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/gpucloud/apis/gpu-cloud-api.md) · [All operations](https://skmtc.dev/gpucloud/apis/gpu-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gpucloud/apis/gpu-cloud-api/revisions/ed530411f5c7?raw)