---
title: "List VMs"
method: GET
path: "/api/v1/vms"
tags: ["Virtual Machines"]
---

# List VMs

`GET /api/v1/vms`

List all virtual machines for the authenticated account.

## Query parameters

- `project_id` string, uuid
- `region` 'us-east'
- `status` 'active' | 'passive' | 'provisioning' | 'booting' | 'initiating' | 'finalizing' | 'failure'
- `limit` integer
- `offset` integer

## Response `200`

List of VMs

- object
  - `success` boolean — Whether the request was successful
  - `data` VM[]
    - `id` string, uuid, required — Unique VM identifier
    - `name` string, required — VM display name
    - `status` 'active' | 'passive' | 'provisioning' | 'booting' | 'initiating' | 'finalizing' | 'failure', required — Current VM status. Lifecycle transitions: - Creation: `initiating` → `provisioning` → `booting` → `active` - Stop: `active` → `finalizing` → `passive` - Start: `passive` → `booting` → `active` - Reboot: `active` → `booting` → `active` | Status | Meaning | Billable | |--------|---------|----------| | `initiating` | Queued, initial setup before provisioning | Yes | | `provisioning` | VM being created in the hypervisor | Yes | | `booting` | VM starting up | Yes | | `active` | Running and accessible | Yes | | `passive` | Stopped, resources still reserved | Yes | | `finalizing` | Shutting down | Yes | | `failure` | Creation or operation failed | No |
    - `cpu` integer, required — Number of vCPU cores
    - `ram` integer, required — RAM in GB
    - `storage` integer, required — Base storage in GB
    - `added_storage` integer, required — Additional storage in GB
    - `total_storage` integer, required — Total storage (base + added) in GB
    - `template_id` string, uuid, required — OS template ID used to create this VM
    - `template_name` string, required — OS template name
    - `template_version` string, required — OS template version
    - `version` string — VM version
    - `price_per_hour` string, required — Hourly billing rate in USD
    - `pricing_id` integer, required — Pricing plan ID
    - `created_by` string — User ID who created this VM
    - `billing_type` 'payg' | 'subscription' — Billing type for this VM
    - `subscription_id` string, uuid — Subscription ID if billing_type is subscription
    - `backup_type` string, nullable — Backup schedule type
    - `region` 'us-east', required — Data center region
    - `project_id` string, uuid — Project this VM belongs to
    - `public_ipv4_address` string — Public IPv4 address
    - `public_ipv6_address` string, nullable — Public IPv6 address
    - `private_ipv4_address` string — Private IPv4 address (VPC)
    - `private_ipv6_address` string, nullable — Private IPv6 address
    - `tags` VMTag[] — Custom tags
      - `id` string, required — Unique tag identifier
      - `name` string, required — Tag name
      - `priority` integer, required — Tag priority (ordering)
      - `created_at` string, date-time, required — When the tag was created
    - `active` boolean, required — Whether the VM is active
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `total` integer — Total number of VMs matching the query

## Other responses

- `401` — Authentication required

---

[API](https://skmtc.net/rafftechnologies/apis/raff-api.md) · [All operations](https://skmtc.net/rafftechnologies/apis/raff-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/rafftechnologies/raff-api/versions/a3f123570011/schema)