| Verb | URI | Description | |||
| GET | /servers?image=imageRef&
flavor=flavorRef&
name=serverName&
status=serverStatus&
marker=markerID&limit=int&
changes-since=dateTime
|
Lists IDs, names, and links for all servers. | |||
| GET | /servers/detail?image=imageRef&
flavor=flavorRef&
name=serverName&
status=serverStatus&
marker=markerID&limit=int&
changes-since=dateTime
|
Lists all details for all servers. | |||
Normal Response Code(s): 200, 203
Error Response Code(s): computeFault (400, 500, …), serviceUnavailable (503), unauthorized (401), forbidden (403), badRequest (400), badMethod (405), overLimit (413)
You can filter the list of servers by image, flavor, name, and status through the respective query parameters.
To filter the list of servers returned in the response body, specify one or more of the following optional parameters in the request URI:
- image
The image reference specified as an ID or full URL.
- flavor
The flavor reference specified as an ID or full URL.
- server
The server name.
- status
The server status. See Server Status Values.
- marker
The ID of the last item in the previous list. See Section 1.5, “Paginated Collections”.
- limit
The page size. See Section 1.5, “Paginated Collections”.
- changes-since
The changes-since time. The list contains servers that have been deleted since the changes-since time. See Section 1.6, “Efficient Polling with the
Changes-SinceParameter”.
This operation does not require a request body.
This operation lists the servers associated with your account. The list does not include servers that have been deleted.
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 server status is one of the following values:
Server Status Values
ACTIVE. The server is active.BUILD. The server has not finished the original build process.DELETED. The server is 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.PASSWORD. The password is being reset on the server.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.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.SHUTOFF. The virtual machine (VM) was powered down by the user, but not through the OpenStack Compute API. For example, the user issued ashutdown -hcommand from within the server instance. If the OpenStack Compute manager detects that the VM was powered down, it transitions the server instance to the SHUTOFF status. If you use the OpenStack Compute API to restart the instance, the instance might be deleted first, depending on the value in theshutdown_terminatedatabase field on the Instance model.SUSPENDED. The server is suspended, either by request or necessity. This status appears for only the following hypervisors: XenServer/XCP, KVM, and ESXi. Review support tickets or contact Rackspace support to determine why the server is in this state.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.
The compute provisioning algorithm has an anti-affinity property that attempts to spread customer VMs across hosts. Under certain situations, VMs from the same customer might be placed on the same host. hostId represents the host your server runs on and can be used to determine this scenario if it is relevant to your application.
![[Note]](../common/images/admon/note.png) | Note |
|---|---|
HostId is unique per account and is not globally unique. |
The following examples show an XML and JSON response for the list servers API operation:
Example 2.1. List Servers Response: XML (detail)
<?xml version="1.0" encoding="UTF-8"?>
<servers xmlns="http://docs.openstack.org/compute/api/v1.1"
xmlns:atom="http://www.w3.org/2005/Atom">
<server id="52415800-8b69-11e0-9b19-734f6af67565"
tenant_id="1234" user_id="5678"
name="sample-server" status="BUILD"
progress="60" hostId="e4d909c290d0fb1ca068ffaddf22cbd0"
updated="2010-10-10T12:00:00Z"
created="2010-08-10T12:00:00Z"
accessIPv4="67.23.10.132"
accessIPv6="::babe:67.23.10.132"
>
<image id="52415800-8b69-11e0-9b19-734f6f006e54">
<atom:link
rel="self"
href="http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"/>
<atom:link
rel="bookmark"
href="http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"/>
</image>
<flavor id="52415800-8b69-11e0-9b19-734f216543fd">
<atom:link
rel="self"
href="http://servers.api.openstack.org/v2/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd"/>
<atom:link
rel="bookmark"
href="http://servers.api.openstack.org/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd"/>
</flavor>
<metadata>
<meta key="Server Label">Web Head 1</meta>
<meta key="Image Version">2.1</meta>
</metadata>
<addresses>
<network id="public">
<ip version="4" addr="67.23.10.132"/>
<ip version="6" addr="::babe:67.23.10.132"/>
<ip version="4" addr="67.23.10.131"/>
<ip version="6" addr="::babe:4317:0A83"/>
</network>
<network id="private">
<ip version="4" addr="10.176.42.16"/>
<ip version="6" addr="::babe:10.176.42.16"/>
</network>
</addresses>
<atom:link
rel="self"
href="http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"/>
<atom:link
rel="bookmark"
href="http://servers.api.openstack.org/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"/>
</server>
<server id="52415800-8b69-11e0-9b19-734f1f1350e5"
tenant_id="1234" user_id="5678"
name="sample-server2"
status="ACTIVE" hostId="9e107d9d372bb6826bd81d3542a419d6"
updated="2010-10-10T12:00:00Z"
created="2010-08-10T12:00:00Z"
accessIPv4="67.23.10.133"
accessIPv6="::babe:67.23.10.133"
>
<image id="52415800-8b69-11e0-9b19-734f5736d2a2">
<atom:link
rel="self"
href="http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f5736d2a2"/>
<atom:link
rel="bookmark"
href="http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f5736d2a2"/>
</image>
<flavor id="52415800-8b69-11e0-9b19-734f216543fd">
<atom:link
rel="self"
href="http://servers.api.openstack.org/v2/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd"/>
<atom:link
rel="bookmark"
href="http://servers.api.openstack.org/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd"/>
</flavor>
<metadata>
<meta key="Server Label">DB 1</meta>
</metadata>
<addresses>
<network id="public">
<ip version="4" addr="67.23.10.133"/>
<ip version="6" addr="::babe:67.23.10.133"/>
</network>
<network id="private">
<ip version="4" addr="10.176.42.17"/>
<ip version="6" addr="::babe:10.176.42.17"/>
</network>
</addresses>
<atom:link
rel="self"
href="http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f1f1350e5"/>
<atom:link
rel="bookmark"
href="http://servers.api.openstack.org/1234/servers/52415800-8b69-11e0-9b19-734f1f1350e5"/>
</server>
</servers>
Example 2.2. List Servers Response: JSON (detail)
{
"servers": [
{
"id": "52415800-8b69-11e0-9b19-734f6af67565",
"tenant_id": "1234",
"user_id": "5678",
"name": "sample-server",
"updated": "2010-10-10T12:00:00Z",
"created": "2010-08-10T12:00:00Z",
"hostId": "e4d909c290d0fb1ca068ffaddf22cbd0",
"status": "BUILD",
"progress": 60,
"accessIPv4" : "67.23.10.132",
"accessIPv6" : "::babe:67.23.10.132",
"image" : {
"id": "52415800-8b69-11e0-9b19-734f6f006e54",
"links": [
{
"rel": "self",
"href": "http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"
},
{
"rel": "bookmark",
"href": "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"
}
]
},
"flavor" : {
"id": "52415800-8b69-11e0-9b19-734f216543fd",
"links": [
{
"rel": "self",
"href": "http://servers.api.openstack.org/v2/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd"
},
{
"rel": "bookmark",
"href": "http://servers.api.openstack.org/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd"
}
]
},
"addresses": {
"public" : [
{
"version": 4,
"addr": "67.23.10.132"
},
{
"version": 6,
"addr": "::babe:67.23.10.132"
},
{
"version": 4,
"addr": "67.23.10.131"
},
{
"version": 6,
"addr": "::babe:4317:0A83"
}
],
"private" : [
{
"version": 4,
"addr": "10.176.42.16"
},
{
"version": 6,
"addr": "::babe:10.176.42.16"
}
]
},
"metadata": {
"Server Label": "Web Head 1",
"Image Version": "2.1"
},
"links": [
{
"rel": "self",
"href": "http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"
},
{
"rel": "bookmark",
"href": "http://servers.api.openstack.org/1234/servers/52415800-8b69-11e0-9b19-734f6af67565"
}
]
},
{
"id": "52415800-8b69-11e0-9b19-734f1f1350e5",
"user_id": "5678",
"name": "sample-server2",
"tenant_id": "1234",
"updated": "2010-10-10T12:00:00Z",
"created": "2010-08-10T12:00:00Z",
"hostId": "9e107d9d372bb6826bd81d3542a419d6",
"status": "ACTIVE",
"accessIPv4" : "67.23.10.133",
"accessIPv6" : "::babe:67.23.10.133",
"image" : {
"id": "52415800-8b69-11e0-9b19-734f5736d2a2",
"links": [
{
"rel": "self",
"href": "http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f5736d2a2"
},
{
"rel": "bookmark",
"href": "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f5736d2a2"
}
]
},
"flavor" : {
"id": "52415800-8b69-11e0-9b19-734f216543fd",
"links": [
{
"rel": "self",
"href": "http://servers.api.openstack.org/v2/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd"
},
{
"rel": "bookmark",
"href": "http://servers.api.openstack.org/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd"
}
]
},
"addresses": {
"public" : [
{
"version": 4,
"addr": "67.23.10.133"
},
{
"version": 6,
"addr": "::babe:67.23.10.133"
}
],
"private" : [
{
"version": 4,
"addr": "10.176.42.17"
},
{
"version": 6,
"addr": "::babe:10.176.42.17"
}
]
},
"metadata": {
"Server Label": "DB 1"
},
"links": [
{
"rel": "self",
"href": "http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f1f1350e5"
},
{
"rel": "bookmark",
"href": "http://servers.api.openstack.org/1234/servers/52415800-8b69-11e0-9b19-734f1f1350e5"
}
]
}
]
}
