1.1. List Servers

Verb	URI	Description
GET	/servers	List all servers (IDs and names only)
GET	/servers/detail	List all servers (all details)

Normal Response Codes: 200 and 203

Error Response Codes: cloudServersFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), overLimit (413)

This operation provides a list of servers associated with your account. Servers that have been deleted are not included in this list.

Servers contain a status attribute that indicate the current server state. 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.
DELETE_IP. An IP address is being removed from the server.
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.
PREP_RESIZE. The server is performing the initial copy of data to its new host. Server should still be active at this time.
QUEUE_RESIZE. The server is in the queue pending a resize or migration. Server should still be active at this time.
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.
SHARE_IP. An IP address is currently being shared with or from this server. The network configuration for this server will change, perhaps requiring an IP address.
SHARE_IP_NO_CONFIG. The host is being reconfigured to allow your server to use an IP from another machine. No configuration change should occur on your guest server, however it might reboot if the kernel is not compatible with the pause state that the hypervisor requests during the process.
SUSPENDED. The server is suspended, either by request or for necessity. 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 Rackspace support.
VERIFY_RESIZE. System is awaiting confirmation that the server is operational after a move or resize.

When retrieving a list of servers through the changes-since parameter (see Section 8, “Efficient Polling with the Changes-Since Parameter”.), the list will contain servers that have been deleted since the changes-since time.

The Cloud Servers provisioning algorithm has an anti-affinity property that attempts to spread out customer VMs across hosts. Under certain situations, VMs from the same customer may be placed on the same host. hostId represents the host your cloud server runs on and can be used to determine this scenario if it is relevant to your application.

	Note
	HostId is unique per account and is not globally unique.

This operation does not require a request body.

To issue a list servers request that returns a JSON response, you can embed the request in a cURL command, as follows:

Example 3.1. List Servers: JSON Request in a cURL Command

$ curl -s https://servers.api.rackspacecloud.com/v1.0/$account/servers/detail \
     -H "X-Auth-Token: $token" | python -m json.tool

Where account is your tenant ID and token is your authentication token.

Example 3.2. List Servers: JSON Response (detail)

{
    "servers": [
        {
            "addresses": {
                "private": [
                    "10.178.54.11"
                ], 
                "public": [
                    "198.101.228.60"
                ]
            }, 
            "flavorId": 2, 
            "hostId": "2d66db781ce490432f55ada17610173e", 
            "id": 21034274, 
            "imageId": 119, 
            "metadata": {
                "My Server Name": "API Test Server"
            }, 
            "name": "api-test-server", 
            "progress": 100, 
            "status": "ACTIVE"
        }, 
        {
            "addresses": {
                "private": [
                    "10.178.54.13"
                ], 
                "public": [
                    "198.101.228.62"
                ]
            }, 
            "flavorId": 2, 
            "hostId": "312452f3d7a72d3def18a06e09ec01b7", 
            "id": 21034280, 
            "imageId": 119, 
            "metadata": {
                "My Server Name": "API Test Server XML"
            }, 
            "name": "api-test-server-xml", 
            "progress": 100, 
            "status": "ACTIVE"
        }
    ]
}

To issue a list servers request that returns an XML response, you can embed the request in a cURL command, as follows:

Example 3.3. List Servers: XML Request in a cURL Command

$ curl -i https://servers.api.rackspacecloud.com/v1.0/$account/servers/detail.xml \
     -H "Content-Type: application/xml" \
     -H "Accept: application/xml" \
     -H "X-Auth-Token: $token"

Where account is your tenant ID and token is your authentication token.

Example 3.4. List Servers: XML Response (detail)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<servers xmlns="http://docs.rackspacecloud.com/servers/api/v1.0">
  <server status="ACTIVE" progress="100"
    hostId="2d66db781ce490432f55ada17610173e" flavorId="2"
    imageId="119" id="21034274" name="api-test-server">
    <metadata>
      <meta key="My Server Name">API Test Server</meta>
    </metadata>
    <addresses>
      <public>
        <ip addr="198.101.228.60"/>
      </public>
      <private>
        <ip addr="10.178.54.11"/>
      </private>
    </addresses>
  </server>
  <server status="ACTIVE" progress="100"
    hostId="312452f3d7a72d3def18a06e09ec01b7" flavorId="2"
    imageId="119" id="21034280" name="api-test-server-xml">
    <metadata>
      <meta key="My Server Name">API Test Server XML</meta>
    </metadata>
    <addresses>
      <public>
        <ip addr="198.101.228.62"/>
      </public>
      <private>
        <ip addr="10.178.54.13"/>
      </private>
    </addresses>
  </server>
</servers>

Legal notices