ec2-describe-spot-price-history

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
	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
`instance-type`	Type of instance (e.g., m1.small). Type: String
`product-description`	Product description for the Spot Price. Type: String Valid Values: `Linux/UNIX` \| `SUSE Linux` \| `Windows` \| `Linux/UNIX (Amazon VPC)` \| `SUSE Linux (Amazon VPC)` \| `Windows (Amazon VPC)`
`spot-price`	Spot Price. The value must match exactly (or use wildcards; greater than or less than comparison is not supported). Type: String
`timestamp`	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
`availability-zone`	The Availability Zone for which prices should be returned. Type: String

The short version of this command is ec2dsph.

Syntax

ec2-describe-spot-price-history [--start-time timestamp] [--end-time timestamp] [--instance-type type] [--product-description description] [[--filter name=value] ...] [--availability-zone zone]

Options

Name	Description	Required
`-s, --start-time` `timestamp`	Start date and time of the Spot Instance price history data. Type: DateTime Default: None Example: -s 2009-12-01T11:51:50.000Z	No
`-e, --end-time` `timestamp`	End date and time of the Spot Instance price history data. Type: DateTime Default: None Example: -e 2009-12-31T11:51:50.000Z	No
`-t, --instance-type` `type`	Specifies the instance type to return. Type: String Valid Values: `m1.small` \| `m1.large` \| `m1.xlarge` \| `c1.medium` \| `c1.xlarge` \| `m2.xlarge` \| `m2.2xlarge` \| `m2.4xlarge` \| `t1.micro` Default: None Example: -t m1.large	No
`-d, --product-description` `description`	Filters the results by basic product description. Type: String Valid Values: `Linux/UNIX` \| `SUSE Linux` \| `Windows` \| `Linux/UNIX (Amazon VPC)` \| `SUSE Linux (Amazon VPC)` \| `Windows (Amazon VPC)` Default: None Example: -d Linux/UNIX	No
`-F, --filter` `name`=`value`	A filter for limiting the results. See the preceding table for a list of allowed filter names and values. If you're using the command line tools on a Windows system, you might need to use quotation marks (i.e., "name=value"). Type: String Default: Lists all available history information, or just that information otherwise specified. Example: --filter "product-description=Linux/UNIX"	No
`-a, --availability-zone` `zone`	The Availability Zone for which you want to get the price history Type: String Default: None Example: us-east-1a	No

Common Options

Option	Description
`--region` `REGION`	Overrides the Region specified in the `EC2_URL` environment variable and the URL specified by the `-U` option. Default: The `EC2_URL` environment variable, or `us-east-1` if the environment variable is not set. Example: `--region eu-west-1`
`-U, --url` `URL`	`URL` is the uniform resource locator of the Amazon EC2 web service entry point. Default: The `EC2_URL` environment variable, or https://ec2.amazonaws.com if the environment variable is not set. Example: `-U https://ec2.amazonaws.com`
`-K, --private-key` `EC2-PRIVATE-KEY`	The private key to use when constructing requests to Amazon EC2. Default: The value of the `EC2_PRIVATE_KEY` environment variable. Example: `-K pk-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem`
`-C, --cert` `EC2-CERT`	The X.509 certificate to use when constructing requests to Amazon EC2. Default: The value of the `EC2_CERT` environment variable. Example: `-C cert-HKZYKTAIG2ECMXYIBH3HXV4ZBEXAMPLE.pem`
`--connection-timeout` `TIMEOUT`	Specifies a connection timeout (in seconds). Example: --connection-timeout 30
`--request-timeout` `TIMEOUT`	Specifies a request timeout (in seconds). Example: --request-timeout 45
`-v, --verbose`	Displays verbose output by showing the SOAP request and response on the command line. This is particularly useful if you are building tools to talk directly to our SOAP API.
`-H, --headers`	Displays column headers in the output.
`--show-empty-fields`	Shows empty columns as `(nil)`.
`--hide-tags`	Do not display tags for tagged resources.
`--debug`	Prints internal debugging information. This is useful to assist us when troubleshooting problems.
`-?, --help, -h`	Displays Help.
`-`	If `-` is specified as an argument to one of the parameters, a list of arguments is read from standard input. This is useful for piping the output of one command into the input of another. Example: `ec2-describe-instances \| grep stopped \| cut -f 2 \| ec2-start-instances -`

Output

The command returns a table that contains the following information:

Output type identifier ("SPOTINSTANCEPRICE")
Price
Date and time
Instance type
Product description (e.g., Linux/UNIX)
Availability Zone (e.g., us-east-1a)

Amazon EC2 command line tools display errors on stderr.

Examples

Example Request

This example returns Spot Price history for m1.small instances for a particular day in May.

PROMPT> ec2-describe-spot-price-history -H --instance-type m1.xlarge --start-time 2011-05-06T07:08:09 --end-time 2011-05-06T08:09:10	
Type	Price	Timestamp	InstanceType	ProductDescription	AvailabilityZone
SPOTINSTANCEPRICE	0.417000	2011-05-06T05:54:03-0800	m1.xlarge	Windows	us-east-1b
SPOTINSTANCEPRICE	0.417000	2011-05-06T05:54:03-0800	m1.xlarge	Windows	us-east-1d
SPOTINSTANCEPRICE	0.417000	2011-05-06T05:54:03-0800	m1.xlarge	Windows	us-east-1a...

The following example uses filters instead of request options to get the same results.

PROMPT> ec2-describe-spot-price-history -H --instance-type m1.xlarge --start-time 2011-05-06T07:08:09 --end-time 2011-05-06T08:09:10 --product-description 'Linux/UNIX'
Type	Price	Timestamp	InstanceType	ProductDescription	AvailabilityZone
SPOTINSTANCEPRICE	0.234000	2011-05-06T05:08:03-0800	m1.xlarge	Linux/UNIX	us-east-1b
SPOTINSTANCEPRICE	0.234000	2011-05-06T05:08:03-0800	m1.xlarge	Linux/UNIX	us-east-1c
SPOTINSTANCEPRICE	0.234000	2011-05-06T05:08:03-0800	m1.xlarge	Linux/UNIX	us-east-1d
…