         | Did this page help you? Yes No Tell us about it... |
DescribeReservedInstances
Description
Describes Reserved Instances that you purchased.
Starting with the 2011-11-01 API version, AWS expanded its offering of Amazon EC2 Reserved
Instances to address a range of projected instance use. There are three types of Reserved Instances based
on customer utilization levels: Heavy Utilization, Medium Utilization,
and Light Utilization. You determine the type of the Reserved Instances offerings by including the optional
offeringType parameter. The Medium Utilization offering type is equivalent to the Reserved
Instance offering available before API version 2011-11-01. If you are using tools that predate the
2011-11-01 API version, you only have access to the Medium Utilization Reserved Instance offering type.
For more information about Reserved Instances, go to Reserved Instances in the Amazon Elastic Compute Cloud User Guide.
You can filter the results to return information about Reserved Instances that matches criteria you specify. For example, you could get information about Reserved Instances in a particular Availability Zone. Or you can specify multiple values for a filter. A Reserved Instance must match at least one of the specified values for it to be included in the results.
You can specify multiple filters as well. For example, you could specify that your Reserved Instance must be in a particular Availability Zone and must be tagged with a particular value. The result includes information for a particular instance only if it matches all of your filters. If there's no match, no special message is returned; the response is simply empty.
You can use wildcards with the filter values: * matches zero or more characters, and ? matches exactly one character. You can escape special characters using a backslash before the character. For example, a value of \*amazon\?\\ searches for the literal string *amazon?\.
The following table shows the available filters.
| Filter Name | Description |
|---|---|
|
|
Availability Zone where the Reserved Instance can be used. Type: String |
|
|
Duration of the Reserved Instance (one year or three years), in seconds. Type: xs:long Valid Values: |
|
|
Purchase price of the Reserved Instance (e.g., Type: xs:double |
|
|
Instance type on which the Reserved Instance can be used. Type: String |
|
|
Reserved Instance description. Type: String Valid Values: |
|
|
Reserved Instance's ID. Type: String |
|
|
Time the Reserved Instance purchase request was placed, e.g., 2010-08-07T11:54:42.000Z. Type: xsd:dateTime |
|
|
State of the Reserved Instance. Type: String Valid Values: |
|
|
Key of a tag assigned to the resource. This filter is independent of the For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide. Type: String |
|
|
Value of a tag assigned to the resource. This filter is independent of the Type: String |
|
|
Filters the results based on a specific tag/value combination. Example: To list just the resources assigned tag Purpose=X, then specify:
Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify:
|
|
|
Usage price of the Reserved Instance, per hour (e.g., Type: xs:double |
Request Parameters
| Name | Description | Required |
|---|---|---|
|
|
One or more Reserved Instance IDs. Type: String Default: Describes all your Reserved Instances, or only those otherwise specified. |
No |
|
|
Name of a filter. See the preceding table for a list of allowed filter names. Type: String Default: None |
No |
|
|
A value for the filter. See the preceding table for a list of allowed values for each filter. Type: String Default: None |
No |
|
|
The Reserved Instance offering type. Type: String Valid Values: |
No |
Response Elements
The elements in the following table are wrapped in a
DescribeReservedInstancesResponse structure.
| Name | Description |
|---|---|
|
|
The ID of the request. Type: xsd:string |
|
|
A list of Reserved Instances. Each Reserved Instance's
information is wrapped in an |
Examples
Example Request
This example describes Reserved Instances owned by your account.
https://ec2.amazonaws.com/?Action=DescribeReservedInstances &AUTHPARAMS
Example Response
<DescribeReservedInstancesResponse xmlns="http://ec2.amazonaws.com/doc/2011-12-15/">
<requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId>
<reservedInstancesSet>
<item>
<reservedInstancesId>4b2293b4-5813-4cc8-9ce3-1957fc1dcfc8EXAMPLE</reservedInstancesId>
<instanceType>m1.xlarge</instanceType>
<availabilityZone>us-east-1a</availabilityZone>
<duration>31536000</duration>
<fixedPrice>1820.0</fixedPrice>
<usagePrice>0.24</usagePrice>
<instanceCount>3</instanceCount>
<productDescription>Linux/UNIX</productDescription>
<state>active</state>
<tagSet/>
</item>
</reservedInstancesSet>
</DescribeReservedInstancesResponse>Example Request
This example filters the results to display only one-year, m1.small Linux/UNIX Reserved Instances. If you want Linux/UNIX Reserved Instances specifically for use with Amazon VPC, set the product descripton to Linux/UNIX (Amazon VPC).
https://ec2.amazonaws.com/?Action=DescribeReservedInstances &Filter.1.Name=duration &Filter.1.Value.1=31536000 &Filter.2.Name=instance-type &Filter.2.Value.1=m1.small &Filter.3.Name=product-description &Filter.3.Value.1=Linux/UNIX &AUTHPARAMS
