Back to guides list

13.1. Listing virtual machines

GET /servers

List virtual machines.

By default the servers are filtered using the project ID associated with the authenticated request.

Servers contain a status attribute that indicates the current server state. You can filter on the server status when you complete a list servers request. The server status is returned in the response body. The possible server status values are:

  • ACTIVE. The server is active.
  • BUILD. The server has not finished the original build process.
  • DELETED. The server is permanently deleted.
  • ERROR. The server is in error.
  • HARD_REBOOT. The server is hard rebooting. This is equivalent to pulling the power plug on a physical server, plugging it back in, and rebooting it.
  • MIGRATING. The server is being migrated to a new host.
  • PASSWORD. The password is being reset on the server.
  • PAUSED. In a paused state, the state of the server is stored in RAM. A paused server continues to run in frozen state.
  • REBOOT. The server is in a soft reboot state. A reboot command was passed to the operating system.
  • REBUILD. The server is currently being rebuilt from an image.
  • RESCUE. The server is in rescue mode. A rescue image is running with the original server image attached.
  • RESIZE. Server is performing the differential copy of data that changed during its initial copy. Server is down for this stage.
  • REVERT_RESIZE. The resize or migration of a server failed for some reason. The destination server is being cleaned up and the original source server is restarting.
  • SHELVED: The server is in shelved state. Depending on the shelve offload time, the server will be automatically shelved offloaded.
  • SHELVED_OFFLOADED: The shelved server is offloaded (removed from the compute host) and it needs unshelved action to be used again.
  • SHUTOFF. The server is powered off and the disk image still persists.
  • SOFT_DELETED. The server is marked as deleted but the disk images are still available to restore.
  • SUSPENDED. The server is suspended, either by request or necessity. When you suspend a server, its state is stored on disk, all memory is written to disk, and the server is stopped. Suspending a server is similar to placing a device in hibernation and its occupied resource will not be freed but rather kept for when the server is resumed. If a server is infrequently used and the occupied resource needs to be freed to create other servers, it should be shelved.
  • UNKNOWN. The state of the server is unknown. Contact your cloud provider.
  • VERIFY_RESIZE. System is awaiting confirmation that the server is operational after a move or resize.

There is whitelist for valid filter keys. Any filter key other than from whitelist will be silently ignored.

  • For non-admin users, whitelist is different from admin users whitelist. The valid whitelist can be configured using the os_compute_api:servers:allow_all_filters policy rule. By default, the valid whitelist for non-admin users includes
    • changes-since
    • flavor
    • image
    • ip
    • ip6 (New in version 2.5)
    • name
    • not-tags (New in version 2.26)
    • not-tags-any (New in version 2.26)
    • reservation_id
    • status
    • tags (New in version 2.26)
    • tags-any (New in version 2.26)
    • changes-before (New in version 2.66)
    • locked (New in version 2.73)
    • availability_zone (New in version 2.83)
    • config_drive (New in version 2.83)
    • key_name (New in version 2.83)
    • created_at (New in version 2.83)
    • launched_at (New in version 2.83)
    • terminated_at (New in version 2.83)
    • power_state (New in version 2.83)
    • task_state (New in version 2.83)
    • vm_state (New in version 2.83)
    • progress (New in version 2.83)
    • user_id (New in version 2.83)
  • For admin user, whitelist includes all filter keys.

Source: https://docs.openstack.org/api-ref/compute/?expanded=#list-servers

13.1.1. Request

Name In Type Description
access_ip_v4 (Optional) query string Filter server list result by IPv4 address that should be used to access the server.
access_ip_v6 (Optional) query string Filter server list result by IPv6 address that should be used to access the server.
all_tenants (Optional) query boolean Specify the all_tenants query parameter to list all instances for all projects. By default this is only allowed by administrators. If this parameter is specified without a value, the value defaults to True. If the value is specified, 1, t, true, on, y and yes are treated as True. 0, f, false, off, n and no are treated as False. (They are case-insensitive.)
auto_disk_config (Optional) query string

Filter the server list result by the disk_config setting of the server, Valid values are:

  • AUTO
  • MANUAL

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.
availability_zone (Optional) query string

Filter the server list result by server availability zone.

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter before microversion 2.83, it will be ignored.
changes-since (Optional) query string

Filters the response by a date and time stamp when the server last changed status. To help keep track of changes this may also return recently deleted servers.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed. When both changes-since and changes-before are specified, the value of the changes-since must be earlier than or equal to the value of the changes-before otherwise API will return 400.
config_drive (Optional) query string

Filter the server list result by the config drive setting of the server.

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter before microversion 2.83, it will be ignored.
created_at (Optional) query string

Filter the server list result by a date and time stamp when server was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed.

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter before microversion 2.83, it will be ignored.
deleted (Optional) query boolean

Show deleted items only. In some circumstances deleted items will still be accessible via the backend database, however there is no contract on how long, so this parameter should be used with caution. 1, t, true, on, y and yes are treated as True (case-insensitive). Other than them are treated as False.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.
description (Optional) query string

Filter the server list result by description.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.

Note

display_description can also be requested which is alias of description but that is not recommended to use as that will be removed in future.
flavor (Optional) query string Filters the response by a flavor, as a UUID. A flavor is a combination of memory, disk size, and CPUs.
host (Optional) query string

Filter the server list result by the host name of compute node.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.
hostname (Optional) query string

Filter the server list result by the host name of server.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.
image (Optional) query string

Filters the response by an image, as a UUID.

Note

‘image_ref’ can also be requested which is alias of ‘image’ but that is not recommended to use as that will be removed in future.
ip (Optional) query string An IPv4 address to filter results by.
ip6 (Optional) query string

An IPv6 address to filter results by.

Up to microversion 2.4, this parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored. Starting from microversion 2.5, this parameter is valid for no-admin users as well as administrators.
kernel_id (Optional) query string

Filter the server list result by the UUID of the kernel image when using an AMI.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.
key_name (Optional) query string

Filter the server list result by keypair name.

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter before microversion 2.83, it will be ignored.
launch_index (Optional) query integer

Filter the server list result by the sequence in which the servers were launched.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.
launched_at (Optional) query string

Filter the server list result by a date and time stamp when the instance was launched. The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed.

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter before microversion 2.83, it will be ignored.
limit (Optional) query integer Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
locked_by (Optional) query string

Filter the server list result by who locked the server, possible value could be admin or owner.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.
marker (Optional) query string The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.
name (Optional) query string

Filters the response by a server name, as a string. You can use regular expressions in the query. For example, the ?name=bob regular expression returns both bob and bobb. If you must match on only bob, you can use a regular expression that matches the syntax of the underlying database server that is implemented for Compute, such as MySQL or PostgreSQL.

Note

‘display_name’ can also be requested which is alias of ‘name’ but that is not recommended to use as that will be removed in future.
node (Optional) query string

Filter the server list result by the node.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.
power_state (Optional) query integer

Filter the server list result by server power state.

Possible values are integer values that is mapped as:

0: NOSTATE
1: RUNNING
3: PAUSED
4: SHUTDOWN
6: CRASHED
7: SUSPENDED
8: SHUTDOWN_ACTIVE

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter before microversion 2.83, it will be ignored.
progress (Optional) query integer

Filter the server list result by the progress of the server. The value could be from 0 to 100 as integer.

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter before microversion 2.83, it will be ignored.
project_id (Optional) query string

Filter the list of servers by the given project ID.

This filter only works when the all_tenants filter is also specified.

Note

‘tenant_id’ can also be requested which is alias of ‘project_id’ but that is not recommended to use as that will be removed in future.
ramdisk_id (Optional) query string

Filter the server list result by the UUID of the ramdisk image when using an AMI.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.
reservation_id (Optional) query string A reservation id as returned by a servers multiple create call.
root_device_name (Optional) query string

Filter the server list result by the root device name of the server.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.
soft_deleted (Optional) query boolean Filter the server list by SOFT_DELETED status. This parameter is only valid when the deleted=True filter parameter is specified.
sort_dir (Optional) query string Sort direction. A valid value is asc (ascending) or desc (descending). Default is desc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the direction of the server sort_key attribute.
sort_key (Optional) query string

Sorts by a server attribute. Default attribute is created_at. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server sort_key attribute. The sort keys are limited to:

  • 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 version 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 are only allowed for admin. If non-admin users specify them, a 403 error is returned.
status (Optional) query string

Filters the response by a server status, as a string. For example, ACTIVE.

Up to microversion 2.37, an empty list is returned if an invalid status is specified. Starting from microversion 2.38, a 400 error is returned in that case.
task_state (Optional) query string

Filter the server list result by task state.

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter before microversion 2.83, it will be ignored.
terminated_at (Optional) query string

Filter the server list result by a date and time stamp when instance was terminated. The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed.

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter before microversion 2.83, it will be ignored.
user_id (Optional) query string

Filter the list of servers by the given user ID.

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter before microversion 2.83, it will be ignored.
uuid (Optional) query string

Filter the server list result by the UUID of the server.

This parameter is only valid when specified by administrators. If non-admin users specify this parameter, it is ignored.
vm_state (Optional) query string

Filter the server list result by vm state.

The value could be:

  • ACTIVE
  • BUILDING
  • DELETED
  • ERROR
  • PAUSED
  • RESCUED
  • RESIZED
  • SHELVED
  • SHELVED_OFFLOADED
  • SOFT_DELETED
  • STOPPED
  • SUSPENDED

This parameter is restricted to administrators until microversion 2.83. If non-admin users specify this parameter before microversion 2.83, it will be ignored.
not-tags (Optional) query string

A list of tags to filter the server list by. Servers that don’t match all tags in this list will be returned. Boolean expression in this case is ‘NOT (t1 AND t2)’. Tags in query must be separated by comma.

New in version 2.26
not-tags-any (Optional) query string

A list of tags to filter the server list by. Servers that don’t match any tags in this list will be returned. Boolean expression in this case is ‘NOT (t1 OR t2)’. Tags in query must be separated by comma.

New in version 2.26
tags (Optional) query string

A list of tags to filter the server list by. Servers that match all tags in this list will be returned. Boolean expression in this case is ‘t1 AND t2’. Tags in query must be separated by comma.

New in version 2.26
tags-any (Optional) query string

A list of tags to filter the server list by. Servers that match any tag in this list will be returned. Boolean expression in this case is ‘t1 OR t2’. Tags in query must be separated by comma.

New in version 2.26
changes-before (Optional) query string

Filters the response by a date and time stamp when the server last changed. Those servers that changed before or equal to the specified date and time stamp are returned. To help keep track of changes this may also return recently deleted servers.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, returns the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. If you omit the time zone, the UTC time zone is assumed. When both changes-since and changes-before are specified, the value of the changes-before must be later than or equal to the value of the changes-since otherwise API will return 400.

New in version 2.66
locked (Optional) query boolean

Specify the locked query parameter to list all locked or unlocked instances. If the value is specified, 1, t, true, on, y and yes are treated as True. 0, f, false, off, n and no are treated as False. (They are case-insensitive.) Any other value provided will be considered invalid.

New in version 2.73

13.1.1.1. Example

# curl -ks -H 'Content-Type: application/json' -H 'X-Auth-Token: gAAAAA<...>' \
https://<node_IP_addr>:8774/v2.1/f5d834d636c642c7bfe8af86139c6f26/servers?all_tenants

13.1.2. Response

Name In Type Description
servers body array A list of server objects.
id body string The UUID of the server.
links body array Links to the resources in question. See API Guide / Links and References for more info.
name body string The server name.
servers_links (Optional) body array Links to the next server. It is available when the number of servers exceeds limit parameter or [api]/max_limit in the configuration file. See Paginated collections for more info.

13.1.2.1. Status codes

13.1.2.1.1. Success

Code Reason
200 - OK Request was successful.

13.1.2.1.2. Error

Code Reason
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.

13.1.2.2. Example

{
  "servers": [
    {
      "id": "79e45166-3768-4d0e-89fb-bf1dc8f0fded",
      "links": [
        {
          "href": "https://<node_IP_addr>:8774/v2.1/f5d834d636c642c7bfe8af86139c6f26/servers/79e45166-3768-4d0e-89fb-bf1dc8f0fded",
          "rel": "self"
        },
        {
          "href": "https://<node_IP_addr>:8774/f5d834d636c642c7bfe8af86139c6f26/servers/79e45166-3768-4d0e-89fb-bf1dc8f0fded",
          "rel": "bookmark"
        }
      ],
      "name": "vm1-selfservice"
    },
    {
      "id": "bb4f4c8d-a6ca-4723-ace3-1683f54cca1e",
      "links": [
        {
          "href": "https://<node_IP_addr>:8774/v2.1/f5d834d636c642c7bfe8af86139c6f26/servers/bb4f4c8d-a6ca-4723-ace3-1683f54cca1e",
          "rel": "self"
        },
        {
          "href": "https://<node_IP_addr>:8774/f5d834d636c642c7bfe8af86139c6f26/servers/bb4f4c8d-a6ca-4723-ace3-1683f54cca1e",
          "rel": "bookmark"
        }
      ],
      "name": "vm1"
    }
  ]
}
Version 5.0.0 — Feb 01, 2022
Print