Deployments - DeployGPU

Create Deployment

Only VM providers (verda, hyperstack, masscompute, latitude) are supported via the API. Container providers (Vast.ai) require the dashboard.

POST /api/v1/deployments

Starts provisioning a new GPU instance. Returns immediately with status provisioning — poll the get endpoint to track progress.

Request Body

{
  "provider": "verda",
  "offer_id": "c0858d33-a3de-4fbd-8fee-98d009c3ec7d",
  "os_image_id": "ubuntu-22.04-cuda-12.4-docker",
  "disk_gb": 100,
  "ssh_key_ids": ["86a3a040-f052-4557-9dc5-4388661a8cfb"],
  "volume_ids": ["e6a12cc1-5d22-48c6-bda3-01fce11c9d19"]
}

Field	Type	Required	Description
`provider`	string	Yes	Provider name (e.g., `verda`, `hyperstack`, `masscompute`, `latitude`)
`offer_id`	string	Yes	Offer UUID from the offers endpoint
`os_image_id`	string	No	OS image ID from the provider images endpoint. If omitted, uses provider default.
`disk_gb`	int	No	Disk size in GB. Must be within the offer’s `storageMinGB`–`storageMaxGB` range. Default: 0 (provider default).
`ssh_key_ids`	string[]	No	SSH key UUIDs to inject. If omitted, all your keys are injected.
`volume_ids`	string[]	No	Volume UUIDs to attach. Volumes must be in the same region as the offer.

Response `202 Accepted`

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

Errors

Code	When
`provider_not_supported`	Container providers (Vast.ai) are not supported via the API
`provider_unavailable`	The provider is not currently configured. Returned as `503 Service Unavailable` before pricing, volume, balance, or provider calls. Choose a provider returned by `GET /api/v1/providers`.
`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 (for example an R535 driver image on a Blackwell B200). The message names the minimum driver.
`image_not_offered`	The OS image is not in the provider 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 provider capacity for this exact offer and location. Returned as `503 Service Unavailable` with `Retry-After` and `error.retry_after` in seconds. Choose another location or wait.
`invalid_volume`	A volume ID is malformed, duplicated, or not owned by you
`volume_unavailable`	A volume is not currently available to attach
`volume_provider_mismatch`	A volume belongs to a different provider than the offer
`volume_location_mismatch`	Volumes span locations, or the offer cannot run where the volume lives
`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": "verda",
      "region": "FIN-01",
      "gpu": {
        "type": "NVIDIA A100 SXM4 80GB",
        "count": 1
      },
      "hourly_rate": "1.4500",
      "accumulated_cost": "1.4500",
      "connection": {
        "public_ip": "135.181.63.213",
        "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-05-10T20:12:51.596837Z",
      "activated_at": "2026-05-10T20:14:35.432129Z",
      "updated_at": "2026-05-10T20: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 at the provider (typically 1–3 minutes)
`connecting`	Instance deployed, establishing SSH connectivity
`active`	Running and accessible via SSH. Billed hourly.
`stopping`	Teardown in progress
`interrupted`	Provider terminated the instance (preemption or health check failure)
`terminated`	Fully shut down
`failed`	Provisioning failed — see Failure Fields for why

Failure Fields

When status is failed, four fields say why. They are set at the moment the failure is recorded and never change afterwards.

Field	Description
`failure_reason`	The cause in the provider’s own words, verbatim — for example `Not enough resources to deploy a 1 GPU instance type 1H100.80S.32V in FIN-01`
`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	The provider had no capacity for this offer and location. Retry in a few minutes or choose another offer.
`VOLUME_LOCATION_PINNED`	yes	An attached volume pinned the deployment to one location, and that location had no capacity. Recreate the volume elsewhere, or retry later.
`VOLUME_LOCATION_MISMATCH`	no	The attached volume is in a different location from the instance.
`IMAGE_INCOMPATIBLE`	no	The OS image cannot run on this GPU type or is not offered for it.
`OFFER_NOT_VM_CAPABLE`	no	A VM template was launched on a host without VM support.
`SSH_KEY_REJECTED`	yes	The provider rejected the SSH key material. Re-upload the key if it persists.
`INVALID_DISK_SIZE`	no	The disk is below the provider minimum.
`INSUFFICIENT_BALANCE`	no	The first hour could not be reserved.
`PROVIDER_INSTANCE_FAILED`	yes	The instance was created but the provider reported it 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 tunnel client never reached our tunnel server.
`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 or the provider.
`PLATFORM_PROVIDER_ISSUE`	yes	A platform-side credential or account problem with the provider.
`DUPLICATE_REQUEST`	no	The same idempotency key was reused with a different body.
`UNKNOWN`	yes	Nothing matched; `failure_reason` still has the provider text.

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 (e.g., `root`, `Ubuntu`)
`jupyter_url`	Jupyter URL if enabled, otherwise null
`tunnel_id`	Bastion tunnel ID if bastion is enabled, otherwise null

Errors

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

Stop Deployment

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

Initiates teardown of a running deployment. The instance is terminated and billing stops. Returns the updated deployment object.

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