List VMs

GET /v2.1/servers

To list all virtual machines (VMs) in your project, you can send a GET request to the /v2.1/servers endpoint of the compute service. This request requires an authentication token, which you should include in the request headers.

Request

Parameters

Name	In	Type	Description
name	query	string	Filter by server name; supports regex (e.g., ?name=bob matches bob and bobb; use DB-specific regex to match only bob). Alias display_name is deprecated.
access_ip_v4	query	string	Filter by IPv4 address used to access the server.
access_ip_v6	query	string	Filter by IPv6 address used to access the server.
all_tenants	query	boolean	List instances from all projects; admin-only by default. If no value, defaults to true. True values: 1,t,true,on,y,yes. False values: 0,f,false,off,n,no (case-insensitive).
auto_disk_config	query	string	Filter by disk_config. Valid: AUTO, MANUAL. Admin-only.
availability_zone	query	string	Filter by availability zone. Admin-only until microversion 2.83; ignored for non-admins before 2.83.
changes-before	query	string	Filter servers changed on/before this ISO 8601 timestamp (CCYY-MM-DDThh:mm:ssZ±hh:mm). Must be > changes-since if both set. New in 2.66.
changes-since	query	string	Filter servers changed on/after this ISO 8601 timestamp (CCYY-MM-DDThh:mm:ssZ±hh:mm). Must be < changes-before if both set.
config_drive	query	string	Filter by config-drive setting. Admin-only until microversion 2.83; ignored for non-admins before 2.83.
created_at	query	string	Filter by creation time (ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm). Admin-only until microversion 2.83; ignored for non-admins before 2.83.
deleted	query	boolean	Show deleted items only. Use with caution. True values: 1,t,true,on,y,yes (case-insensitive). Others treated as false. Admin-only.
flavor	query	string	Filter by flavor UUID.
image	query	string	Filter by image UUID. Alias image_ref is deprecated.
ip	query	string	Filter by IPv4 address.
ip6	query	string	Filter by IPv6 address. Admin-only up to 2.4; available to all from 2.5.
kernel_id	query	string	Filter by kernel image UUID (AMI). Admin-only.
key_name	query	string	Filter by keypair name. Admin-only until microversion 2.83; ignored for non-admins before 2.83.
launch_index	query	integer	Filter by sequence in which servers were launched. Admin-only.
launched_at	query	string	Filter by launch time (ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm). Admin-only until microversion 2.83; ignored for non-admins before 2.83.
limit	query	integer	Page size. Use with marker for pagination.
locked	query	boolean	List locked or unlocked instances. True values: 1,t,true,on,y,yes. False values: 0,f,false,off,n,no (case-insensitive). Invalid values are errors. New in 2.73.
locked_by	query	string	Filter by who locked the server (admin or owner). Admin-only.
marker	query	string	ID of the last-seen item for pagination.
description	query	string	Filter by description. Admin-only. Alias display_description is deprecated.
host	query	string	Filter by compute host name. Admin-only.
hostname	query	string	Filter by server host name. Admin-only.
node	query	string	Filter by node. Admin-only.
power_state	query	integer	Filter by power state. 0 NOSTATE, 1 RUNNING, 3 PAUSED, 4 SHUTDOWN, 6 CRASHED, 7 SUSPENDED, 8 SHUTDOWN_ACTIVE. Admin-only until microversion 2.83; ignored for non-admins before 2.83.
progress	query	integer	Filter by progress (0–100). Admin-only until microversion 2.83; ignored for non-admins before 2.83.
project_id	query	string	Filter by project ID. Requires all_tenants. Alias tenant_id is deprecated.
ramdisk_id	query	string	Filter by ramdisk image UUID (AMI). Admin-only.
reservation_id	query	string	Filter by reservation id from multi-create.
root_device_name	query	string	Filter by root device name. Admin-only.
soft_deleted	query	boolean	Filter by SOFT_DELETED status; only valid when deleted=true.
sort_dir	query	string	Sort direction: asc or desc (default desc). Can be paired multiple times with sort_key.
sort_key	query	string	Sort by attribute (default created_at). Allowed: access_ip_v4, access_ip_v6, auto_disk_config, availability_zone, config_drive, created_at, display_description, display_name, host, hostname, image_ref, instance_type_id, kernel_id, key_name, launch_index, launched_at, locked (new in 2.73), locked_by, node, power_state, progress, project_id, ramdisk_id, root_device_name, task_state, terminated_at, updated_at, user_id, uuid, vm_state. host and node require admin; non-admins get 403.
status	query	string	Filter by server status (e.g., ACTIVE). Up to 2.37, invalid status returns empty list; from 2.38, returns 400.
task_state	query	string	Filter by task state. Admin-only until microversion 2.83; ignored for non-admins before 2.83.
terminated_at	query	string	Filter by termination time (ISO 8601 CCYY-MM-DDThh:mm:ss±hh:mm). Admin-only until microversion 2.83; ignored for non-admins before 2.83.
user_id	query	string	Filter by user ID. Admin-only until microversion 2.83; ignored for non-admins before 2.83.
uuid	query	string	Filter by server UUID. Admin-only.
vm_state	query	string	Filter by VM state. One of: ACTIVE, BUILDING, DELETED, ERROR, PAUSED, RESCUED, RESIZED, SHELVED, SHELVED_OFFLOADED, SOFT_DELETED, STOPPED, SUSPENDED. Admin-only until microversion 2.83; ignored for non-admins before 2.83.
not-tags	query	string	Return servers that do not match all tags in list (NOT (t1 AND t2)); comma-separated. New in 2.26.
not-tags-any	query	string	Return servers that do not match any tag in list (NOT (t1 OR t2)); comma-separated. New in 2.26.
tags	query	string	Return servers that match all tags in list (t1 AND t2); comma-separated. New in 2.26.
tags-any	query	string	Return servers that match any tag in list (t1 OR t2); comma-separated. New in 2.26.

Sample Request

Using curl

curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' \
https://api.vietnix.cloud:8774/v2.1/servers

Using HTTP request

GET https://api.vietnix.cloud:8774/v2.1/servers

Response

{
    "servers": [
        {
            "id": "393210ad-152b-4ac3-a0f0-798ee4e93620",
            "name": "Ubuntu22",
            "links": [
                {
                    "rel": "self",
                    "href": "https://api.vietnix.cloud:8774/v2.1/servers/393210ad-152b-4ac3-a0f0-798ee4e93620"
                },
                {
                    "rel": "bookmark",
                    "href": "https://api.vietnix.cloud:8774/servers/393210ad-152b-4ac3-a0f0-798ee4e93620"
                }
            ]
        }
    ]
}

Status Code

Success

Status Code	Description
200 - OK	Request was successful.

Error

Status Code	Description
400 - Bad Request	Some content in the request was invalid.
401 - Unauthorized	User must authenticate before making a request.
403 - Forbidden	Policy does not allow current user to do this operation.