Skip to main content

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​

namestringrequired

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_v4stringrequired

Filter by IPv4 address used to access the server.

access_ip_v6stringrequired

Filter by IPv6 address used to access the server.

all_tenantsbooleanrequired

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_configstringrequired

Filter by disk_config. Valid: AUTO, MANUAL. Admin-only.

availability_zonestringrequired

Filter by availability zone. Admin-only until microversion 2.83; ignored for non-admins before 2.83.

changes-beforestringrequired

Filter servers changed on/before this ISO 8601 timestamp (CCYY-MM-DDThh:mm±hh). Must be > changes-since if both set. New in 2.66.

changes-sincestringrequired

Filter servers changed on/after this ISO 8601 timestamp (CCYY-MM-DDThh:mm±hh). Must be < changes-before if both set.

config_drivestringrequired

Filter by config-drive setting. Admin-only until microversion 2.83; ignored for non-admins before 2.83.

created_atstringrequired

Filter by creation time (ISO 8601 CCYY-MM-DDThh:mm±hh). Admin-only until microversion 2.83; ignored for non-admins before 2.83.

deletedbooleanrequired

Show deleted items only. Use with caution. True values: 1,t,true,on,y,yes (case-insensitive). Others treated as false. Admin-only.

flavorstringrequired

Filter by flavor UUID.

imagestringrequired

Filter by image UUID. Alias image_ref is deprecated.

ipstringrequired

Filter by IPv4 address.

ip6stringrequired

Filter by IPv6 address. Admin-only up to 2.4; available to all from 2.5.

kernel_idstringrequired

Filter by kernel image UUID (AMI). Admin-only.

key_namestringrequired

Filter by keypair name. Admin-only until microversion 2.83; ignored for non-admins before 2.83.

launch_indexintegerrequired

Filter by sequence in which servers were launched. Admin-only.

launched_atstringrequired

Filter by launch time (ISO 8601 CCYY-MM-DDThh:mm±hh). Admin-only until microversion 2.83; ignored for non-admins before 2.83.

limitintegerrequired

Page size. Use with marker for pagination.

lockedbooleanrequired

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_bystringrequired

Filter by who locked the server (admin or owner). Admin-only.

markerstringrequired

ID of the last-seen item for pagination.

descriptionstringrequired

Filter by description. Admin-only. Alias display_description is deprecated.

hoststringrequired

Filter by compute host name. Admin-only.

hostnamestringrequired

Filter by server host name. Admin-only.

nodestringrequired

Filter by node. Admin-only.

power_stateintegerrequired

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.

progressintegerrequired

Filter by progress (0–100). Admin-only until microversion 2.83; ignored for non-admins before 2.83.

project_idstringrequired

Filter by project ID. Requires all_tenants. Alias tenant_id is deprecated.

ramdisk_idstringrequired

Filter by ramdisk image UUID (AMI). Admin-only.

reservation_idstringrequired

Filter by reservation id from multi-create.

root_device_namestringrequired

Filter by root device name. Admin-only.

soft_deletedbooleanrequired

Filter by SOFT_DELETED status; only valid when deleted=true.

sort_dirstringrequired

Sort direction: asc or desc (default desc). Can be paired multiple times with sort_key.

sort_keystringrequired

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.

statusstringrequired

Filter by server status (e.g., ACTIVE). Up to 2.37, invalid status returns empty list; from 2.38, returns 400.

task_statestringrequired

Filter by task state. Admin-only until microversion 2.83; ignored for non-admins before 2.83.

terminated_atstringrequired

Filter by termination time (ISO 8601 CCYY-MM-DDThh:mm±hh). Admin-only until microversion 2.83; ignored for non-admins before 2.83.

user_idstringrequired

Filter by user ID. Admin-only until microversion 2.83; ignored for non-admins before 2.83.

uuidstringrequired

Filter by server UUID. Admin-only.

vm_statestringrequired

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

Return servers that do not match all tags in list (NOT (t1 AND t2)); comma-separated. New in 2.26.

not-tags-anystringrequired

Return servers that do not match any tag in list (NOT (t1 OR t2)); comma-separated. New in 2.26.

tagsstringrequired

Return servers that match all tags in list (t1 AND t2); comma-separated. New in 2.26.

tags-anystringrequired

Return servers that match any tag in list (t1 OR t2); comma-separated. New in 2.26.

Sample Request​

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

Response​

Response 200
{
    "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 CodeDescription
200 - OKRequest was successful.

Error​

Status CodeDescription
400 - Bad RequestSome content in the request was invalid.
401 - UnauthorizedUser must authenticate before making a request.
403 - ForbiddenPolicy does not allow current user to do this operation.