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: DescribeInstancesResponse
Children: None
reservationSet
Reservation set.
Type: ReservationSetType
Ancestor: DescribeInstancesResponse
Children: item
item
Information for a reservation.
Type: ReservationInfoType
Ancestor: reservationSet
Children: reservationId, ownerId, groupSet, and instancesSet
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, and monitoring
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: xsd:string
Ancestor: item
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: xsd:string
Ancestor: item
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
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-04-04/">
<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>