Get a virtual machine by ID

GET

https://api.americancloud.com/api/v1/compute/vms/:id

GET

/api/v1/compute/vms/:id

curl https://api.americancloud.com/api/v1/compute/vms/123e4567-e89b-12d3-a456-426614174000 \
     -H "X-API-Client-ID: <apiKey>"

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "my-vm",
  "status": "STARTED",
  "region": "sjc0",
  "cpu": 4,
  "memoryMb": 8192,
  "rootDiskGb": 50,
  "image": "ubuntu-22.04",
  "ipAddress": "192.168.1.10",
  "networkName": "production-network",
  "networkId": "123e4567-e89b-12d3-a456-426614174000",
  "rootVolumeId": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2026-05-29T12:34:56Z",
  "vmPackage": "standard-2-4",
  "tags": [
    "production",
    "web-tier"
  ],
  "subscriptionPeriod": "monthly",
  "imageDisplayName": "Ubuntu 22.04 LTS",
  "versionStartedAt": "2026-05-29T12:34:56Z",
  "marketplaceApp": {
    "label": "coolify",
    "name": "Coolify",
    "docsUrl": "https://coolify.io/docs"
  }
}

Authentication

X-API-Client-IDstring

API Client ID

X-API-Client-Secretstring

API Client Secret

Path parameters

idstringRequired

ID of the virtual machine

Response

The virtual machine

idstringformat: "uuid"

Unique identifier for this virtual machine.

namestring

Human-readable name for the VM. Shown in dashboards and CLI output.

statusstring

Current lifecycle state of the VM. Observed values include CREATING, STARTING, CREATED, STARTED, STOPPING, STOPPED, and DESTROYED. Treat this as an open set — new states may be introduced over time.

regionstring

Region the VM is provisioned in. References a region label from /v1/compute/regions.

cpuinteger

Number of virtual CPUs allocated to the VM.

memoryMbinteger

Memory allocated to the VM, in megabytes.

rootDiskGbinteger

Root disk size, in gigabytes.

imagestring

Image label the VM was provisioned from. References /v1/compute/images.

ipAddressstringformat: "ipv4"

Primary IP address assigned to the VM on its network.

networkNamestring or null

Name of the network or VPC tier this VM is attached to. Null while the VM is still provisioning.

networkIdstring or nullformat: "uuid"

Identifier of the network or VPC tier this VM is attached to. Null while the VM is still provisioning.

rootVolumeIdstring or nullformat: "uuid"

Identifier of the VM root volume. Null while the VM is still provisioning.

createdAtdatetime

When the VM was first provisioned.

vmPackagestringOptional

Package label identifying the CPU/memory/disk preset this VM uses.

tagslist of stringsOptional

Tags assigned to this VM for grouping and filtering.

subscriptionPeriodstringOptional

Billing cadence applied to this VM. Absent for a few moments after the VM is created, while the billing term is still being recorded. Poll until it appears.

imageDisplayNamestringOptional

Friendly name of the source image.

versionStartedAtdatetimeOptional

When the current billing version started (set when the VM is scaled or its disk is resized). Only present if the VM has been modified since creation.

marketplaceAppobjectOptional

Source marketplace app, when the VM was deployed from one. Absent for OS-only deploys.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error