Deployments - QuantaCloud

Create Deployment

POST /api/v1/deployments

Starts provisioning a new GPU instance. Returns immediately with status provisioning — poll the get endpoint to track progress. API deployments boot the base image (Ubuntu 22.04 with NVIDIA drivers and Docker) and inject your SSH keys, the same as the Bare Metal template in the console.

Request Body

{
  "provider": "quantacloud",
  "offer_id": "3b101e48-fdd9-469a-b0b2-1d43438a3e9b",
  "os_image_id": "default",
  "ssh_key_ids": ["86a3a040-f052-4557-9dc5-4388661a8cfb"]
}

Field	Type	Required	Description
`provider`	string	Yes	Always `quantacloud`
`offer_id`	string	Yes	Offer UUID from the offers endpoint
`os_image_id`	string	No	OS image ID from the images endpoint. If omitted, the default image is used.
`disk_gb`	int	No	Disk size in GB. QuantaCloud offers include a fixed disk (`storageMinGB` equals `storageMaxGB`), so this can be omitted.
`ssh_key_ids`	string[]	No	SSH key UUIDs to inject, from List SSH Keys. Each must be one of your keys. If omitted or empty, all your keys are injected.

Response `202 Accepted`

{
  "id": "a6305686-fe03-494c-b254-9ee0a2453068",
  "status": "provisioning"
}

Errors

Code	When
`provider_not_found`	`provider` is not `quantacloud`
`offer_provider_mismatch`	The offer belongs to a different provider than the `provider` in the request
`validation_error`	Invalid offer, provider, or parameters
`image_incompatible`	The OS image cannot boot on this GPU type. The message names the minimum driver.
`image_not_offered`	The OS image is not in the catalog for this offer. The message lists the images that are.
`offer_unavailable`	The offer is out of stock or was withdrawn since you fetched it
`offer_cooling_down`	A recent attempt hit capacity for this exact offer and location. Returned as `503 Service Unavailable` with `Retry-After` and `error.retry_after` in seconds. Choose another offer or wait.
`invalid_ssh_key`	An SSH key ID is malformed or not one of your keys — for example, a deleted key or a key ID from another account
`insufficient_balance`	Balance doesn’t cover at least 1 hour at the offer’s rate

These are all returned before anything is created or charged. Failures that happen after the request is accepted are reported on the deployment itself — see Failure Fields.

List Deployments

GET /api/v1/deployments

Returns your deployments, newest first.

Query Parameters

Param	Type	Default	Description
`page`	int	0	Page number (0-indexed)
`size`	int	25	Page size (max 100)

Response

{
  "data": [
    {
      "id": "a6305686-fe03-494c-b254-9ee0a2453068",
      "status": "active",
      "provider": "quantacloud",
      "region": "us-midwest-1",
      "gpu": {
        "type": "NVIDIA RTX A6000",
        "count": 1
      },
      "hourly_rate": "0.5280",
      "accumulated_cost": "0.5280",
      "connection": {
        "public_ip": "203.0.113.10",
        "ssh_port": 22,
        "ssh_user": "root",
        "jupyter_url": null,
        "tunnel_id": null
      },
      "stop_reason": null,
      "failure_reason": null,
      "failure_code": null,
      "retryable": null,
      "suggested_action": null,
      "billing_iterations": 0,
      "created_at": "2026-09-20T20:12:51.596837Z",
      "activated_at": "2026-09-20T20:14:35.432129Z",
      "updated_at": "2026-09-20T20:15:03.908535Z"
    }
  ],
  "page": 0,
  "size": 25,
  "total_elements": 12
}

Get Deployment

GET /api/v1/deployments/{id}

Returns a single deployment by ID. Same shape as items in the list response.

Deployment Status

Status	Description
`provisioning`	Instance is being created (typically 1–3 minutes)
`connecting`	Instance deployed, establishing SSH connectivity
`active`	Running and accessible via SSH. Billed hourly.
`stopping`	Teardown in progress
`interrupted`	The instance was terminated outside your control (host failure or health check failure)
`terminated`	Fully shut down
`failed`	Provisioning failed — see Failure Fields for why

Failure Fields

When status is failed, these fields explain the failure and the next step. Internal service details are replaced with a generic customer message.

Field	Description
`failure_reason`	A customer-facing explanation. Internal service issues use a generic message; diagnostic details are kept internally.
`failure_code`	A stable code you can branch on (table below)
`retryable`	`true` if retrying the same request later is sensible; `false` if something in the request must change first
`suggested_action`	One sentence: what to do about it

`failure_code`	Retryable	Meaning
`PROVIDER_CAPACITY`	yes	No capacity for this offer and location. Retry in a few minutes or choose another offer.
`IMAGE_INCOMPATIBLE`	no	The OS image cannot run on this GPU type or is not offered for it.
`SSH_KEY_REJECTED`	yes	The SSH key material was rejected. Re-upload the key if it persists.
`SSH_KEY_MISSING`	no	No usable SSH key was sent — for example, only ECDSA keys were selected. Deploy with an RSA or Ed25519 key.
`INVALID_DISK_SIZE`	no	The requested disk does not match the offer. Omit `disk_gb`.
`INSUFFICIENT_BALANCE`	no	The first hour could not be reserved.
`PROVIDER_INSTANCE_FAILED`	yes	The instance was created but reported as failed. A retry usually lands on a different host.
`INSTANCE_BOOT_TIMEOUT`	yes	The instance never became ready within the wait window.
`TUNNEL_NEVER_REGISTERED`	yes	The instance booted but its app tunnel never connected (app templates only).
`APP_HEALTH_TIMEOUT`	yes	The tunnel connected but the application never passed its health check — common with large images that take longer than the window to pull.
`USER_CANCELLED`	yes	The deployment was stopped while provisioning.
`WORKER_INTERRUPTED`	yes	A platform worker restarted mid-provision. Not caused by you.
`PLATFORM_PROVIDER_ISSUE`	yes	A temporary service issue. Contact support before retrying.
`DUPLICATE_REQUEST`	no	The same idempotency key was reused with a different body.
`UNKNOWN`	yes	The failure could not be classified. Contact support with the deployment ID.

retryable describes whether a new request may succeed later. It does not mean that the current request will be retried automatically. A reserved first hour is always refunded when provisioning fails, whatever the code.

Connection Fields

Connection info is null until the deployment reaches active status:

Field	Description
`public_ip`	Instance IP address
`ssh_port`	SSH port (usually 22)
`ssh_user`	SSH username (usually `root`)
`jupyter_url`	Browser URL for app templates deployed from the console, otherwise null
`tunnel_id`	Tunnel ID for app templates, otherwise null

Errors

404 not_found — Deployment doesn’t exist or isn’t owned by you.

Stop Deployment

POST /api/v1/deployments/{id}/stop
DELETE /api/v1/deployments/{id}

Both endpoints initiate the same teardown flow. The instance is terminated and billing stops. Both return 200 OK with the updated deployment object and retain the deployment’s history.

Response

{
  "id": "a6305686-fe03-494c-b254-9ee0a2453068",
  "status": "stopping",
  "stop_reason": "USER_REQUESTED",
  ...
}

Errors

Code	When
`not_found`	Deployment not found
`validation_error`	Cannot stop (already stopping, terminated, or failed)

​Create Deployment

​Request Body

​Response 202 Accepted

​Errors

​List Deployments

​Query Parameters

​Response

​Get Deployment

​Deployment Status

​Failure Fields

​Connection Fields

​Errors

​Stop Deployment

​Response

​Errors

Create Deployment

Request Body

Response `202 Accepted`

Errors

List Deployments

Query Parameters

Response

Get Deployment

Deployment Status

Failure Fields

Connection Fields

Errors

Stop Deployment

Response

Errors