AWS Documentation » Amazon EC2 » API Reference » Actions » DescribeReservedInstancesOfferings	« Previous Next »
	Did this page help you? Yes \| No \| Tell us about it...

DescribeReservedInstancesOfferings

Description

Describes Reserved Instance offerings that are available for purchase. With Amazon EC2 Reserved Instances, you purchase the right to launch Amazon EC2 instances for a period of time. During that time period you will not receive insufficient capacity errors, and you will pay a lower usage rate than the rate charged for On-Demand instances for the actual time used.

Starting with the 2011-11-01 API version, AWS expanded its offering of Amazon EC2 Reserved Instances to address a range of projected instance usage. 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 when calling DescribeReservedInstancesOfferings. 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, DescribeReservedInstancesOfferings will only list information about the Medium Utilization Reserved Instance offering type.

For information about Reserved Instances pricing, go to Understanding Reserved Instance Pricing Tiers in the Amazon Elastic Compute Cloud User Guide. For more information about Reserved Instances, go to Reserved Instances also in the Amazon Elastic Compute Cloud User Guide.

Starting with the 2012-08-15 API version, AWS offers the Reserved Instance Marketplace, where you can buy and sell Reserved Instances. The Reserved Instance Marketplace matches sellers who want to resell Reserved Instance capacity that they no longer need with buyers who want to purchase additional capacity. Reserved Instances bought and sold through the Reserved Instance Marketplace work like any other Reserved Instances.

By default, with the 2012-08-15 API version, DescribeReservedInstancesOfferings returns information about AWS and Reserved Instance Marketplace offerings. If you are using tools that predate the 2012-08-15 API version, DescribeReservedInstancesOfferings will only list information about the Amazon EC2 Reserved Instance offerings.

For more information about the Reserved Instance Marketplace, go to Reserved Instance Marketplace in the Amazon Elastic Compute Cloud User Guide.

Request Parameters

ReservedInstancesOfferingId.n

One or more Reserved Instances offering IDs.

Type: String

Default: None

Required: No

InstanceType

The Amazon EC2 instance type on which the Reserved Instance can be used. See Available Instance Types for more information.

Type: String

Default: None

Required: No

AvailabilityZone

The Availability Zone in which the Reserved Instance can be used.

Type: String

Default: None

Required: No

ProductDescription

The Reserved Instance description. Instances that include (Amazon VPC) in the description are for use with Amazon VPC.

Type: String

Valid Values: Linux/UNIX | Linux/UNIX (Amazon VPC) | Windows | Windows (Amazon VPC)

Default: None

Required: No

Filter.n.Name

The name of a filter. See the Supported Filters section for a list of supported filter names.

Type: String

Default: None

Required: No

Filter.n.Value.m

A value for the filter. See the Supported Filters section for a list of supported values for each filter.

Type: String

Default: None

Required: No

InstanceTenancy

The tenancy of the Reserved Instance offering. A Reserved Instance with tenancy of dedicated will run on single-tenant hardware and can only be launched within a VPC.

Type: String

Valid Values: default | dedicated

Default: default

Required: No

OfferingType

The Reserved Instance offering type.

Type: String

Valid values: Heavy Utilization | Medium Utilization | Light Utilization

Default: None

Required: No

IncludeMarketplace

Include Marketplace offerings in the response.

Type: Boolean

Default: true

Required: No

MinDuration

Minimum duration (in seconds) to filter when searching for offerings.

Type: Long

Default: 2592000 (1 month)

Required: No

MaxDuration

Maximum duration (in seconds) to filter when searching for offerings.

Type: Long

Default: 94608000 (3 years)

Required: No

MaxInstanceCount

Maximum number of instances to filter when searching for offerings.

Type: Integer

Default: 20

Required: No

NextToken

Token to use when requesting the next paginated set of offerings.

Type: String

Default: First page of results if the string is empty.

Required: No

MaxResults

Maximum number of offerings to return.

Type: Integer

Default: 1000

Maximum: 1000

Required: No

Supported Filters

Our policy is to provide filters for all ec2-describe calls so that you can limit the response to your specified criteria. Therefore, you can use filters to limit the response when describing Reserved Instances offerings, even though you can use other options instead.

For example, you could use an option or a filter to get the offerings for a specific instance type. You can specify multiple options or filters (for example, limit the response to the m2.xlarge instance type, and only for Windows instances). The response includes information for an offering only if it matches all options or filters. If there's no match, no special message is returned, the response is simply empty.

You can use wildcards in a filter value. An asterisk (*) matches zero or more characters, and a question mark (?) 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 are the available filters.

availability-zone

The Availability Zone where the Reserved Instance can be used.

Type: String

duration

The duration of the Reserved Instance (for example, one year or three years), in seconds.

Type: Long

Valid values: 31536000 | 94608000

fixed-price

The purchase price of the Reserved Instance (for example, 9800.0)

Type: Double

instance-type

The Amazon EC2 instance type on which the Reserved Instance can be used.

Type: String

marketplace

Set to true to show only Reserved Instance Marketplace offerings. When this filter is not used, which is the default behavior, all offerings from AWS and Reserved Instance Marketplace are listed.

Type: Boolean

product-description

The description of the Reserved Instance.

Type: String

Valid values: Linux/UNIX | Linux/UNIX (Amazon VPC) | Windows | Windows (Amazon VPC)

reserved-instances-offering-id

The Reserved Instances offering ID.

Type: String

usage-price

The usage price of the Reserved Instance, per hour (for example, 0.84)

Type: Double

Response Elements

The following elements are returned in a DescribeReservedInstancesOfferingsResponse element.

requestId

The ID of the request.

Type: xsd:string

reservedInstancesOfferingsSet

A list of Reserved Instances offerings. Each offering's information is wrapped in an item element.

Type: DescribeReservedInstancesOfferingsResponseSetItemType

nextToken

The next paginated set of results to return.

Type: String

Examples

Example Describing Reserved Instance Marketplace Offerings Only

This example requests a list of Linux/UNIX, Light Utilization Reserved Instances that are available through the Reserved Instance Marketplace only.

https://ec2.amazonaws.com/?Action=DescribeReservedInstancesOfferings
&Filter.0.Name=marketplace
&Filter.0.Value.1=true
&IncludeMarketplace=true
&OfferingType=Light+Utilization
&ProductDescription=Linux%2FUNIX&
&Version=2012-08-15
&AUTHPARAMS

Note

When using the Query API the “/” is denoted as “%2F”.

This is the response listing Reserved Instance Marketplace offerings only.

<DescribeReservedInstancesOfferingsResponse xmlns="http://ec2.amazonaws.com/doc/2013-02-01/">
    <requestId>2bc7dafa-dafd-4257-bdf9-c0814EXAMPLE</requestId>
    <reservedInstancesOfferingsSet>
        <item>
            <reservedInstancesOfferingId>a6ce8269-7b8c-42cd-a7f5-0841c726be4c</reservedInstancesOfferingId>
            <instanceType>m1.large</instanceType>
            <availabilityZone>&region_iad;&az1;</availabilityZone>
            <duration>90720000</duration>
            <fixedPrice>4083.333333</fixedPrice>
            <usagePrice>0.124</usagePrice>
            <productDescription>Linux/UNIX</productDescription>
            <instanceTenancy>default</instanceTenancy>
            <currencyCode>USD</currencyCode>
            <offeringType>Light Utilization</offeringType>
            <recurringCharges/>
            <marketplace>true</marketplace>
            <pricingDetailsSet>
                <item>
                    <price>4083.333333</price>
                    <count>1</count>
                </item>
            </pricingDetailsSet>
        </item>
        <item>
            <reservedInstancesOfferingId>9948307c-4e03-4ffb-8bd3-8dea689513cb</reservedInstancesOfferingId>
            <instanceType>m1.xlarge</instanceType>
            <availabilityZone>&region_iad;&az2;</availabilityZone>
            <duration>28512000</duration>
            <fixedPrice>430.0</fixedPrice>
            <usagePrice>0.0</usagePrice>
            <productDescription>Linux/UNIX</productDescription>
            <instanceTenancy>default</instanceTenancy>
            <currencyCode>USD</currencyCode>
            <offeringType>Light Utilization</offeringType>
            <recurringCharges>
                <item>
                    <frequency>Hourly</frequency>
                    <amount>0.29</amount>
                </item>
            </recurringCharges>
            <marketplace>true</marketplace>
            <pricingDetailsSet>
                <item>
                    <price>430.0</price>
                    <count>2</count>
                </item>
            </pricingDetailsSet>
        </item>
    </reservedInstancesOfferingsSet>
</DescribeReservedInstancesOfferingsResponse>

Example Describing AWS Offerings Only

By default, with the 2012-08-15 API version, DescribeReservedInstancesOfferings returns information about AWS Reserved Instances and Reserved Instance Marketplace offerings. If you want a list of AWS offerings only, set IncludeMarketplace to false.

https://ec2.amazonaws.com/?Action=DescribeReservedInstancesOfferings
&IncludeMarketplace=false
&Version=2012-08-15
&AUTHPARAMS

Example Using MaxResults and nextToken to Manage Results

API version 2012-08-15 provides pagination support, which means that you can query the results sequentially and in parts. Use MaxResults to specify the maximum number of results that will be returned in the response. Then each paginated response will contain a nextToken, which can be provided as input to a subsequent DescribeReservedInstancesOfferings call to fetch the next page.

https://ec2.amazonaws.com/?Action=DescribeReservedInstancesOfferings
&MaxResults=5
&Version=2012-08-15
&AUTHPARAMS

The response should look similar to the following example.

<DescribeReservedInstancesOfferingsResponse>
    <requestId>d072f652-cc57-458c-89e0-e6c02EXAMPLE</requestId>
    <reservedInstancesOfferingsSet>
        <item>
            <reservedInstancesOfferingId>649fd0c8-7846-46b8-8f84-a6400ea2a8f4</reservedInstancesOfferingId>
            <instanceType>m1.large</instanceType>
            <availabilityZone>&region_iad;&az1;</availabilityZone>
            <duration>94608000</duration>
            <fixedPrice>1200.0</fixedPrice>
            <usagePrice>0.0</usagePrice>
            <productDescription>Linux/UNIX (Amazon VPC)</productDescription>
            <instanceTenancy>default</instanceTenancy>
            <currencyCode>USD</currencyCode>
            <offeringType>Heavy Utilization</offeringType>
            <recurringCharges>
                <item>
                    <frequency>Hourly</frequency>
                    <amount>0.052</amount>
                </item>
            </recurringCharges>
            <marketplace>false</marketplace>
            <pricingDetailsSet/>
        </item>
        <item>
            <reservedInstancesOfferingId>e5a2ff3b-a4f3-477c-8928-dbd0016caddb</reservedInstancesOfferingId>
            <instanceType>m1.large</instanceType>
            <availabilityZone>&region_iad;&az1;</availabilityZone>
            <duration>94608000</duration>
            <fixedPrice>1000.0</fixedPrice>
            <usagePrice>0.076</usagePrice>
            <productDescription>Linux/UNIX (Amazon VPC)</productDescription>
            <instanceTenancy>default</instanceTenancy>
            <currencyCode>USD</currencyCode>
            <offeringType>Medium Utilization</offeringType>
            <recurringCharges/>
            <marketplace>false</marketplace>
            <pricingDetailsSet/>
        </item>
...
    </reservedInstancesOfferingsSet>
    <nextToken>h/C8YKPQBHEjW8xKz1827/Zzyb0VqsqkjRo3TqhFYeE=</nextToken>
</DescribeReservedInstancesOfferingsResponse>

Then, you can use the nextToken to fetch the next page. The request should look like the following example.

https://ec2.amazonaws.com/?Action=DescribeReservedInstancesOfferings
&MaxResults=5
&NextToken=h/C8YKPQBHEjW8xKz1827/Zzyb0VqsqkjRo3TqhFYeE=
&Version=2012-08-15
&AUTHPARAMS

The response should be similar to the following example.

<DescribeReservedInstancesOfferingsResponse>
    <requestId>652900ca-902c-42fa-b8ae-da67bEXAMPLE</requestId>
    <reservedInstancesOfferingsSet>
        <item>
            <reservedInstancesOfferingId>438012d3-496e-4ab3-b1f6-38ffe8469244</reservedInstancesOfferingId>
            <instanceType>m1.large</instanceType>
            <availabilityZone>&region_iad;&az1;</availabilityZone>
            <duration>94608000</duration>
            <fixedPrice>425.2</fixedPrice>
            <usagePrice>0.124</usagePrice>
            <productDescription>Linux/UNIX</productDescription>
            <instanceTenancy>default</instanceTenancy>
            <currencyCode>USD</currencyCode>
            <offeringType>Light Utilization</offeringType>
            <recurringCharges/>
            <marketplace>false</marketplace>
            <pricingDetailsSet/>
        </item>
        <item>
            <reservedInstancesOfferingId>248e7b75-579e-4599-a34d-cb6aa9ba2ac8</reservedInstancesOfferingId>
            <instanceType>m1.large</instanceType>
            <availabilityZone>&region_iad;&az1;</availabilityZone>
            <duration>31536000</duration>
            <fixedPrice>780.0</fixedPrice>
            <usagePrice>0.0</usagePrice>
            <productDescription>Linux/UNIX</productDescription>
            <instanceTenancy>default</instanceTenancy>
            <currencyCode>USD</currencyCode>
            <offeringType>Heavy Utilization</offeringType>
            <recurringCharges>
                <item>
                    <frequency>Hourly</frequency>
                    <amount>0.064</amount>
                </item>
            </recurringCharges>
            <marketplace>false</marketplace>
            <pricingDetailsSet/>
        </item>
...
    </reservedInstancesOfferingsSet>
    <nextToken>69AJRhm9bxVUF8YCKAs2HsQjyqa246eTkVv23eNFTKw=</nextToken>
</DescribeReservedInstancesOfferingsResponse>

Example Request

This example describes available Reserved Instance offerings.

https://ec2.amazonaws.com/?Action=DescribeReservedInstancesOfferings
&AUTHPARAMS

Example Response

<DescribeReservedInstancesOfferingsResponse xmlns="http://ec2.amazonaws.com/doc/2013-02-01/">
      <requestId>48692a1d-3036-48fd-8c0e-d34681b97efdEXAMPLE</requestId>
      <reservedInstancesOfferingsSet>
        <item>
          <reservedInstancesOfferingId>248e7b75-c83a-48c1-bcf7-b7f03e9c43feEXAMPLE</reservedInstancesOfferingId>
          <instanceType>c1.medium</instanceType>
          <availabilityZone>&region_iad;&az2;</availabilityZone>
          <duration>94608000</duration>
          <fixedPrice>700.0</fixedPrice>
          <usagePrice>0.06</usagePrice>
          <productDescription>Linux/UNIX (Amazon VPC)</productDescription>
          <instanceTenancy>default</instanceTenancy>
          <currencyCode>USD</currencyCode>
          <offeringType>Medium Utilization</offeringType>
          <recurringCharges/>
        </item>
      ...
   </reservedInstancesOfferingsSet> 
</DescribeReservedInstancesOfferingsResponse>

Example Request

This example filters the response to include only one-year, m1.small or m1.large Linux/UNIX Reserved Instances. If you want Linux/UNIX Reserved Instances specifically for use with a VPC, set the product description to Linux/UNIX (Amazon VPC).

https://ec2.amazonaws.com/?Action=DescribeReservedInstancesOfferings
&Filter.1.Name=duration
&Filter.1.Value.1=31536000
&Filter.2.Name=instance-type
&Filter.2.Value.1=m1.small
&Filter.2.Value.2=m1.large
&Filter.3.Name=product-description
&Filter.3.Value.1=Linux/UNIX
&AUTHPARAMS

Document Conventions	« Previous Next »
Terms of Use	Did this page help you? Yes \| No \| Tell us about it...

DescribeReservedInstancesOfferings

Description

Request Parameters

Supported Filters

Response Elements

Examples

Example Describing Reserved Instance Marketplace Offerings Only

Example Describing AWS Offerings Only

Example Using MaxResults and nextToken to Manage Results

Example Request

Example Response

Example Request

Related Actions