DescribeInstances

Amazon Elastic Compute Cloud: 2009-07-15

previous page next page

DescribeInstances

Description

Returns information about instances that you own.

If you specify one or more instance IDs, Amazon EC2 returns information for those instances. If you do not specify instance IDs, Amazon EC2 returns information for all relevant instances. If you specify an invalid instance ID, a fault is returned. If you specify an instance that you do not own, it will not be included in the returned results.

Recently terminated instances might appear in the returned results.This interval is usually less than one hour.

Request Parameters

NameDescriptionRequired

DescribeInstancesType

DescribeInstancesType element.

Type:

DescribeInstancesType

Ancestor: None

Children: instancesSet

instancesSet

Instances set.

Type: DescribeInstancesInfoType

Ancestor: DescribeInstancesType

Children: item

Yes, but can be empty

item

Information for one instance set.

Type: DescribeInstancesItemType

Ancestor: instancesSet

Children: instanceId

No

instanceId

Instance IDs to describe.

Type: xsd:string

Default: Returns all instances.

Ancestor: item

Children: None

No

Response Elements

Name Description

DescribeInstancesResponseType

DescribeInstancesResponseType element.

Type: DescribeInstancesResponseType

Ancestor: None

Children: requestId, reservationSet

requestId

The ID of the request.

Type: xsd:string

Ancestor: DescribeInstancesResponseType

Children: None

reservationSet

Reservation set.

Type: ReservationSetType

Ancestor: DescribeInstancesResponseType

Children: item

item

Information for a reservation.

Type: ReservationInfoType

Ancestor: reservationSet

Children: reservationId, ownerId, groupSet, instancesSet, and requesterId

reservationId

Unique ID of the reservation.

Type: xsd:string

Ancestor: item

Children: None

ownerId

AWS Access Key ID of the user who owns the reservation.

Type: xsd:string

Ancestor: item

Children: None

groupSet

Group set.

Type: GroupSetType

Ancestor: item

Children: item

item

Group set item.

Type: GroupItemType

Ancestor: groupSet

Children: groupId

groupId

Name of the security group.

Type: xsd:string

Ancestor: item

Children: None

instancesSet

Instance set.

Type: RunningInstancesSetType

Ancestor: item

Children: item

item

Running instance set item.

Type: RunningInstancesItemType

Ancestor: instancesSet

Children: instanceId, imageId, instanceState, privateDnsName, dnsName, reason, keyName, amiLaunchIndex, productCodes, instanceType, launchTime, placement, kernelId, ramdiskId, platform, monitoring, subnetId, vpcId, privateIpAddress, and ipAddress

instanceId

Unique ID of the instance launched.

Type: xsd:string

Ancestor: item

Children: None

imageId

Image ID of the AMI used to launch the instance.

Type: xsd:string

Ancestor: item

Children: None

instanceState

The current state of the instance.

Type: InstanceStateType

Ancestor: item

Children: code, name

code

A 16-bit unsigned integer. The high byte is an opaque internal value and should be ignored. The low byte is set based on the state represented:

Type: xsd:int

Ancestor: instanceState

Children: None

name

The current state of the instance.

Type: xsd:string

Ancestor: instanceState

Children: None

privateDnsName

The private DNS name assigned to the instance. This DNS name can only be used inside the Amazon EC2 network. This element remains empty until the instance enters a running state.

Type: xsd:string

Ancestor: item

Children: None

dnsName

The public DNS name assigned to the instance. This DNS name is contactable from outside the Amazon EC2 network. This element remains empty until the instance enters a running state.

Type: xsd:string

Ancestor: item

Children: None

reason

Reason for the most recent state transition. This might be an empty string.

Type: xsd:string

Ancestor: item

Children: None

keyName

If this instance was launched with an associated key pair, this displays the key pair name.

Type: xsd:string

Ancestor: item

Children: None

amiLaunchIndex

The AMI launch index, which can be used to find this instance within the launch group. For more information, go to the Metadata section of the

Type: xsd:string

Ancestor: item

Children: None

productCodes

Product codes attached to this instance.

Type: ProductCodesSetType

Ancestor: item

Children: item

item

Information for one product code.

Type: ProductCodesSetItemType

Ancestor: productCodes

Children: productCode

productCode

Product code.

Type: xsd:string

Ancestor: item

Children: None

instanceType

The instance type. For more information on instance types, go to the

Type: xsd:string

Ancestor: item

Children: None

launchTime

The time the instance launched.

Type: xsd:dateTime

Ancestor: item

Children: None

placement

The location where the instance launched.

Type: PlacementResponseType

Ancestor: item

Children: availabilityZone

availabilityZone

Returns the Availability Zones of the instances.

Type: xsd:string

Ancestor: placement

Children: None

kernelId

Optional. Kernel associated with this instance.

Type: xsd:string

Ancestor: item

Children: None

ramdiskId

Optional. RAM disk associated with this instance.

Type: xsd:string

Ancestor: item

Children: None

platform

Platform of the instance (e.g., Windows).

Type: xsd:string

Ancestor: item

Children: None

monitoring

Specifies whether monitoring is enabled for the instance.

Type: InstanceMonitoringStateType

Ancestor: item

Children: state

state

State of monitoring for the instance.

Type: xsd:string

Ancestor: monitoring

Children: None

subnetId

Specifies the subnet ID in which the instance is running (Amazon Virtual Private Cloud).

Type: xsd:string

Ancestor: item

Children: None

vpcId

Specifies the VPC in which the instance is running (Amazon VPC).

Type: xsd:string

Ancestor: item

Children: None

privateIpAddress

Specifies the private IP address that is assigned to the instance (Amazon VPC).

Type: xsd:string

Ancestor: item

Children: None

ipAddress

Specifies the IP address of the instance.

Type: xsd:string

Ancestor: item

Children: None

requesterId

ID of the requester.

Type: xsd:string

Ancestor: item

Children: None

Examples

Example Request

This example describes the current state of the instances owned by this user.

<DescribeInstances xmlns="http://ec2.amazonaws.com/doc/2009-07-15/">
  <instancesSet/>
</DescribeInstances>

Example Response

<DescribeInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2009-07-15/">
  <reservationSet>
    <item>
      <reservationId>r-44a5402d</reservationId>
      <ownerId>UYY3TLBUXIEON5NQVUUX6OMPWBZIQNFM</ownerId>
      <groupSet>
        <item>
          <groupId>default</groupId>
        </item>
      </groupSet>
      <instancesSet>
        <item>
          <instanceId>i-28a64341</instanceId>
          <imageId>ami-6ea54007</imageId>
          <instanceState>
            <code>0</code>
            <name>running</name>
          </instanceState>
          <privateDnsName>10-251-50-132.ec2.internal</privateDnsName>
          <dnsName>ec2-72-44-33-4.compute-1.amazonaws.com</dnsName>
          <keyName>example-key-name</keyName>
          <amiLaunchIndex>23</amiLaunchIndex>
          <productCodesSet>
            <item><productCode>774F4FF8</productCode></item>
          </productCodesSet>
          <instanceType>m1.large</instanceType>
          <launchTime>2007-08-07T11:54:42.000Z</launchTime>
          <placement>
			  <availabilityZone>us-east-1b</availabilityZone>
	  </placement>
	  <kernelId>aki-ba3adfd3</kernelId>
	  <ramdiskId>ari-badbad00</ramdiskId>
        </item>
        <item>
          <instanceId>i-28a64435</instanceId>
          <imageId>ami-6ea54007</imageId>
          <instanceState>
            <code>0</code>
            <name>running</name>
          </instanceState>
          <privateDnsName>10-251-50-134.ec2.internal</privateDnsName>
          <dnsName>ec2-72-44-33-6.compute-1.amazonaws.com</dnsName>
          <keyName>example-key-name</keyName>
          <amiLaunchIndex>23</amiLaunchIndex>
          <productCodesSet>
            <item><productCode>774F4FF8</productCode></item>
          </productCodesSet>
          <instanceType>m1.large</instanceType>
          <launchTime>2007-08-07T11:54:42.000Z</launchTime>
          <placement>
			  <availabilityZone>us-east-1b</availabilityZone>
	  </placement>
	  <kernelId>aki-ba3adfd3</kernelId>
	  <ramdiskId>ari-badbad00</ramdiskId>
        </item>
      </instancesSet>
    </item>
  </reservationSet>
</DescribeInstancesResponse>
previous page start next page