Amazon Elastic Compute Cloud
API Reference (API Version 2011-12-15)
AWS Documentation » Amazon EC2 » API Reference » Actions » DescribeSpotInstanceRequests
Print this pageEmail this pageGo to the ForumsView the PDFShare this page on TwitterShare this page on FacebookBookmark this page on DeliciousSubmit this page to RedditSubmit this page to DiggDid this page help you?  Yes  No   Tell us about it...

DescribeSpotInstanceRequests

Description

Describes the Spot Instance requests that belong to your account. 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.

You can filter the results to return information only about Spot Instance requests that match criteria you specify. For example, you could get information about requests where the Spot Price you specified is a certain value (however, you can't use greater than or less than comparison, but you can use * and ? wildcards). You can specify multiple values for a filter. A Spot Instance request must match at least one of the specified values for it to be included in the results.

You can specify multiple filters (e.g., the Spot Price is equal to a particular value, and the instance type is m1.small). The result includes information for a particular request only if it matches all 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-group

Availability Zone group. If you specify the same Availability Zone group for all Spot Instance requests, all Spot Instances are launched in the same Availability Zone.

Type: String

create-time

Time stamp when the Spot Instance request was created.

Type: String

fault-code

Fault code related to the request.

Type: String

fault-message

Fault message related to the request.

Type: String

instance-id

ID of the instance that fulfilled the request.

Type: String

launch-group

Spot Instance launch group. Launch groups are Spot Instances that launch together and terminate together.

Type: String

launch.block-device-mapping.delete-on-termination

Whether an Amazon EBS volume mapped to the instance is deleted on instance termination.

Type: Boolean

launch.block-device-mapping.device-name

Device name (e.g., /dev/sdh) for an Amazon EBS volume mapped to the instance.

Type: String

launch.block-device-mapping.snapshot-id

ID for a snapshot mapped to the instance.

Type: String

launch.block-device-mapping.volume-size

Size of an Amazon EBS volume mapped to the instance (in GiB).

Type: String

launch.group-id

A security group the instance is in.

Type: String

launch.image-id

The AMI ID.

Type: String

launch.instance-type

Type of instance (e.g., m1.small).

Type: String

launch.kernel-id

Kernel ID.

Type: String

launch.key-name

Name of the key pair the instance launched with.

Type: String

launch.monitoring-enabled

Whether monitoring is enabled for the Spot Instance.

Type: Boolean

launch.ramdisk-id

RAM disk ID.

Type: String

product-description

Product description associated with the instance.

Type: String

Valid Values: Linux/UNIX | Windows

spot-instance-request-id

Spot Instance request ID.

Type: String

spot-price

Maximum hourly price for any Spot Instance launched to fulfill the request.

Type: String

state

State of the Spot Instance request.

Type: String

Valid Values: active | cancelled | open | closed | failed

tag-key

Key of a tag assigned to the resource. This filter is independent of the tag-value filter. For example, if you use both the filter tag-key=Purpose and the filter tag-value=X, you get any resources assigned both the tag key Purpose (regardless of what the tag's value is), and the tag value X (regardless of what the tag's key is). If you want to list only resources where Purpose=X, see the tag:key filter later in this table.

For more information about tags, go to Using Tags in the Amazon Elastic Compute Cloud User Guide.

Type: String

tag-value

Value of a tag assigned to the resource. This filter is independent of the tag-key filter.

Type: String

tag:key

Filters the results based on a specific tag/value combination.

Example: To list just the resources assigned tag Purpose=X, then specify:

Filter.1.Name=tag:Purpose

Filter.1.Value.1=X

Example: To list just resources assigned tag Purpose=X OR Purpose=Y, then specify:

Filter.1.Name=tag:Purpose

Filter.1.Value.1=X

Filter.1.Value.2=Y

type

Type of Spot Instance request.

Type: String

Valid Values: one-time | persistent

launched-availability-zone

The Availability Zone in which the bid is launched.

Type: String

Valid Values: us-east-1a, etc.

valid-from

Start date of the request.

Type: xsd:dateTime

valid-until

End date of the request.

Type: xsd:dateTime

Request Parameters

NameDescriptionRequired

SpotInstanceRequestId.n

One or more Spot Instance request IDs.

Type: String

Default: None

No

Filter.n.Name

Name of a filter. See the preceding table for a list of allowed filter names.

Type: String

Default: None

No

Filter.n.Value.m

A value for the filter. See the preceding table for a list of allowed values for each filter.

Type: String

Default: None

No

Response Elements

The elements in the following table are wrapped in a DescribeSpotInstanceRequestsResponse structure.

NameDescription

requestId

The ID of the request.

Type: xsd:string

spotInstanceRequestSet

A list of Spot Instance requests. Each request's information is wrapped in an item element.

Type: SpotInstanceRequestSetItemType

Examples

Example Request

This example returns information about current Spot Instance requests.

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

Example Response

<DescribeSpotInstanceRequestsResponse xmlns="http://ec2.amazonaws.com/doc/2011-12-15/"
  <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId>
  <spotInstanceRequestSet>     
    <item>
       <spotInstanceRequestId>sir-e1471206</spotInstanceRequestId>
       <spotPrice>0.09</spotPrice>
       <type>one-time</type>
       <state>active</state>
       <launchSpecification>
          <imageId>ami-813968c4</imageId>
          <keyName>MyKey</keyName>
          <groupSet>
             <item>
                <groupId>default</groupId>
             </item>
          </groupSet>
          <instanceType>m1.small</instanceType>
          <blockDeviceMapping/>
          <monitoring>
             <enabled>false</enabled>
          </monitoring>
       </launchSpecification>
       <instanceId>i-992cf7dd&lt;/instanceId>
       <createTime>2010-09-13T23:50:44.000Z</createTime>
       <productDescription>Linux/UNIX</productDescription>
       <launchedAvailabilityZone>us-east-1c</launchedAvailabilityZone>
    </item>
  <spotInstanceRequestSet/>
<DescribeSpotInstanceRequestsResponse>

Example Request

This example describes all persistent Spot Instance requests that have resulted in the launch of at least one m1.small instance, that has been fulfilled in the us-east-1a Availability Zone, and that also has monitoring enabled.

https://ec2.amazonaws.com/?Action=DescribeSpotInstanceRequests
&Filter.1.Name=type
&Filter.1.Value.1=persistent
&Filter.2.Name=instance-type
&Filter.2.Value.1=m1.small
&Filter.3.Name=monitoring-enabled
&Filter.3.Value.1=true
&Filter.4.Name=launched-availability-zone
&Filter.4.Value.1=us-east-1a
&AUTHPARAMS
Document Conventions
Terms of Use		Did this page help you?  Yes  No   Tell us about it...