---
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

## Changes

- **2026-05-06** `9e13a6e23934` — 1 warning, 21 info
  - removed the optional property `data/items/vm_id` from the response with the `200` status
  - the response property `data/items/active` became required for the status `200`
  - the response property `data/items/added_storage` became required for the status `200`
  - the response property `data/items/cpu` became required for the status `200`
  - …18 more
- **2026-03-20** `51e2355a0abe` — 1 breaking, 1 warning, 5 info
  - the `data/items/tags/items/` response's property type/format changed from `string`/`` to `object`/`` for status `200`
  - removed the optional property `data/items/reserved_ip` from the response with the `200` status
  - added the optional property `data/items/tags/items/created_at` to the response with the `200` status
  - added the optional property `data/items/tags/items/id` to the response with the `200` status
  - …3 more
- **2026-03-12** `e50d1f442cca` — 1 breaking, 1 warning, 1 info
  - the `query` request parameter `region` was restricted to a list of enum values
  - added the new `us-east` enum value to the `data/items/region` response property for the response status `200`
  - added the new enum value `us-east` to the `query` request parameter `region`

[Change history](https://skmtc.dev/rafftechnologies/apis/raff-api/changes/api/v1/vms/get.md)

---

[API](https://skmtc.dev/rafftechnologies/apis/raff-api.md) · [All operations](https://skmtc.dev/rafftechnologies/apis/raff-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/rafftechnologies/raff-api/revisions/2f4df56be77c/schema)