         | Did this page help you? Yes No Tell us about it... |
DescribeSpotPriceHistory
Description
Describes the Spot Price history. Spot Instances are instances that Amazon EC2 starts on your behalf when the maximum price that you specify exceeds the current Spot Price. Amazon EC2 periodically sets the Spot Price based on available Spot Instance capacity and current Spot Instance requests. For more information about Spot Instances, go to Spot Instances in the Amazon Elastic Compute Cloud User Guide.
When you use the availability-zone option, this command describes the price history for the specified Availability Zone
with the most recent set of prices listed first. If you don't specify an Availability Zone, the command returns the prices across all Availability Zones,
starting with the most recent set. However, if you use this command with versions of the API earlier than the 2011-05-15 version, this command returns the
lowest price across the Region for the given time period. The prices returned will be listed in chronological order — from the oldest to the most recent.
![[Note]](http://docs.amazonwebservices.com/docs-common/images/note.png) | Note |
|---|---|
Our policy is to provide filters for all "describe" calls so you can limit the results to your specified criteria. Therefore, you can use filters to limit the results when describing Spot Price histories, even though you can use the regular request parameters to do something similar. |
For example, you could use the regular request parameters or a filter to get the history for a particular instance type. You can specify multiple request parameters or multiple filters (e.g., limit the results to the m2.xlarge instance type, and only for Windows instances). The result includes information for a particular price history only if it matches all your request parameters or 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 |
|---|---|
|
|
Type of instance (e.g., m1.small). Type: String |
|
|
Product description for the Spot Price. Type: String Valid Values: |
|
|
Spot Price. The value must match exactly (or use wildcards; greater than or less than comparison is not supported). Type: String |
|
|
Timestamp of the Spot Price history, e.g., 2010-08-16T05:06:11.000Z. You can use wildcards (* and ?). Greater than or less than comparison is not supported. Type: xsd:dateTime |
|
|
The Availability Zone for which prices should be returned. Type: String |
Request Parameters
| Name | Description | Required |
|---|---|---|
|
|
Start date and time of the Spot Instance price history data. Type: DateTime Default: None |
No |
|
|
End date and time of the Spot Instance price history data. Type: DateTime Default: None |
No |
|
|
The instance type to return. Type: String Valid Values: Default: None |
No |
|
|
Filters the results by basic product description. Type: String Valid Values: Default: Returns all information |
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 |
|
|
Filters the results by availability zone. Type: String Valid Values: Default: None |
No |
|
|
Specifies the number of rows to return. Type: int Valid Values: >0 Default: None |
No |
|
|
Specifies the next set of rows to return. Type: String Valid Values: A NextToken value returned by a previous call of the API. Default: None |
No |
Response Elements
The elements in the following table are wrapped in a
DescribeSpotPriceHistoryResponse structure.
| Name | Description |
|---|---|
|
|
The ID of the request. Type: xsd:string |
|
|
List of historical Spot Prices. Each price's information is
wrapped in an |
|
|
The string marking the next set of results returned. Displays empty if there are no more results to be returned. Type: xsd:string |
Examples
Example Request
This example returns Spot Price history for a particular day in December 2009 for Availability Zone us-east-1a.
https://ec2.amazonaws.com/?Action=DescribeSpotPriceHistory &StartTime=2009-12-04T00:00:00.000Z &EndTime=2009-12-04T23:59:59.000Z &AvailabilityZone=us-east-1a &AUTHPARAMS
This request uses filters instead of regular request parameters to achieve the same results.
https://ec2.amazonaws.com/?Action=DescribeSpotPriceHistory &Filter.1.Name=timestamp &Filter.1.Value.1=2009-12-04* &Filter.2.Name=availability-zone &Filter.2.Value.1=us-east-1a &AUTHPARAMS
Example Response
<DescribeSpotPriceHistoryResponse xmlns="http://ec2.amazonaws.com/doc/2011-12-15/">
<requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId>
<spotPriceHistorySet>
<item>
<instanceType>m1.small</instanceType>
<productDescription>Linux/UNIX</productDescription>
<spotPrice>0.287</spotPrice>
<timestamp>2009-12-04T20:56:05.000Z</timestamp>
<availabilityZone>us-east-1a</availabilityZone>
</item>
<item>
<instanceType>m1.small</instanceType>
<productDescription>Windows</productDescription>
<spotPrice>0.033</spotPrice>
<timestamp>2009-12-04T22:33:47.000Z</timestamp>
<availabilityZone>us-east-1a</availabilityZone>
</item>
</spotPriceHistorySet>
<nextToken/>
</DescribeSpotPriceHistoryResponse>
