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
| Name | Description | Required |
|---|---|---|
| Instance IDs to describe. Type: String Default: Returns all instances. | No |
Response Elements
| Name | Description |
|---|---|
|
Type: |
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, ipAddress, stateReason, architecture, rootDeviceType, rootDeviceName, and blockDeviceMapping
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
Valid Values: 0 (pending) | 16 (running) | 32 (shutting-down) | 48 (terminated) | 64 (stopping) | 80 (stopped)
Ancestor: instanceState
Children: None
name
The current state of the instance.
Type: xsd:string
Valid Values: pending | running | shutting-down | terminated | stopping | stopped
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.
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.
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 Zone of the instance.
Type: xsd:string
Ancestor: placement
Children: None
kernelId
Kernel associated with this instance.
Type: xsd:string
Ancestor: item
Children: None
ramdiskId
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
Valid Values: monitoring-enabled (enabled) | monitoring-pending (pending) | monitoring-disabling (disabling) | monitoring-disabled (disabled)
Ancestor: monitoring
Children: None
subnetId
Specifies the Amazon VPC subnet ID in which the instance is running.
Type: xsd:string
Ancestor: item
Children: None
vpcId
Specifies the Amazon VPC in which the instance is running.
Type: xsd:string
Ancestor: item
Children: None
privateIpAddress
Specifies the private IP address that is assigned to the instance.
Type: xsd:string
Ancestor: item
Children: None
ipAddress
Specifies the IP address of the instance.
Type: xsd:string
Ancestor: item
Children: None
stateReason
The reason for the state change.
Type: StateReasonType
Ancestor: item
Children: code, message
code
Reason code for the state change.
Type: xsd:string
Ancestor: stateReason
Children: None
message
Message for the state change.
Type: xsd:string
Ancestor: stateReason
Children: None
architecture
The architecture of the image.
Type: xsd:string
Valid Values: i386 | x86_64
Ancestor: item
Children: None
rootDeviceType
The root device type used by the AMI. The AMI can use an Amazon EBS or instance store root device.
Type: xsd:string
Valid Values: ebs | instance-store
Ancestor: item
Children: None
rootDeviceName
The root device name (e.g., /dev/sda1).
Type: xsd:string
Ancestor: item
Children: None
blockDeviceMapping
Block device mapping set.
Type: InstanceBlockDeviceMappingResponseType
Ancestor: item
Children: item
item
The item element.
Type: InstanceBlockDeviceMappingResponseItemType
Ancestor: blockDeviceMapping
Children: deviceName, ebs
deviceName
Specifies how the device is exposed to the instance (e.g., /dev/sdh).
Type: xsd:string
Ancestor: item
Children: None
ebs
Specifies parameters used to automatically setup Amazon EBS volumes when the instance is launched.
Type: EbsInstanceBlockDeviceMappingResponseType
Ancestor: item
Children: volumeId, status, attachTime, and deleteOnTermination
volumeId
The ID of the Amazon EBS volume.
Type: xsd:string
Ancestor: ebs
Children: None
status
Attachment state.
Type: xsd:string
Valid Values: attaching | attached | detaching | detached
Ancestor: ebs
Children: None
attachTime
Time stamp when the attachment initiated.
Type: xsd:dateTime
Ancestor: ebs
Children: None
deleteOnTermination
Specifies whether the Amazon EBS volume is deleted on instance termination.
Type: xsd:boolean
Ancestor: ebs
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.
https://ec2.amazonaws.com/?Action=DescribeInstances&AuthParams
Example Response
<DescribeInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2009-10-31/">
<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>