Amazon Elastic Compute Cloud
API Reference (API Version 2013-02-01)
AWS Documentation » Amazon EC2 » API Reference » Actions » DescribeSpotInstanceRequests
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...
Filter View:

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, see Spot Instances in the Amazon Elastic Compute Cloud User Guide.

Request Parameters

SpotInstanceRequestId.n

One or more Spot Instance request IDs.

Type: String

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

Supported Filters

You can specify filters so that the response includes information for only certain Spot Instance requests. For example, you can use a filter to specify that you're interested in requests where the Spot Price is a specific value. (You can't use a greater than or less than comparison, however you can use * and ? wildcards.) You can specify multiple values for a filter. The response includes information for a Spot Instance request only if it matches at least one of the filter values that you specified.

You can specify multiple filters; for example, specify that the Spot Price is a specific value, and that the instance type is m1.small. The response includes information for a request only if it matches all the filters that you specified. 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-group

The 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

The time stamp when the Spot Instance request was created.

Type: String

fault-code

The fault code related to the request.

Type: String

fault-message

The fault message related to the request.

Type: String

instance-id

The ID of the instance that fulfilled the request.

Type: String

launch-group

The 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 the Amazon EBS volume is deleted on instance termination.

Type: Boolean

launch.block-device-mapping.device-name

The device name (for example, /dev/sdh) for the Amazon EBS volume.

Type: String

launch.block-device-mapping.snapshot-id

The ID of the snapshot used for the Amazon EBS volume.

Type: String

launch.block-device-mapping.volume-size

The volume size of the Amazon EBS volume, in GiB.

Type: String

launch.block-device-mapping.volume-type

The volume type of the Amazon EBS volume.

Type: String

Valid values: standard | io1

launch.group-id

The security group for the instance.

Type: String

launch.image-id

The ID of the AMI.

Type: String

launch.instance-type

The type of instance (for example, m1.small).

Type: String

launch.kernel-id

The kernel ID.

Type: String

launch.key-name

The 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

The RAM disk ID.

Type: String

launch.network-interface.network-interface-id

The ID of the network interface.

Type: String

launch.network-interface.device-index

The index of the device for the network interface attachment on the instance.

Type: Integer

launch.network-interface.subnet-id

The ID of the subnet for the instance.

Type: String

launch.network-interface.description

A description of the network interface.

Type: String

launch.network-interface.private-ip-address

The primary private IP address of the network interface.

Type: String

launch.network-interface.delete-on-termination

Indicates whether the network interface is deleted when the instance is terminated.

Type: Boolean

launch.network-interface.group-id

The ID of the security group associated with the network interface.

Type: String

launch.network-interface.group-name

The name of the security group associated with the network interface.

Type: String

launch.network-interface.addresses.primary

Indicates whether the IP address is the primary private IP address.

Type: String

product-description

The product description associated with the instance.

Type: String

Valid values: Linux/UNIX | Windows

spot-instance-request-id

The Spot Instance request ID.

Type: String

spot-price

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

Type: String

state

The state of the Spot Instance request. Spot bid status information can help you track your Amazon EC2 Spot Instance requests. For information, see Tracking Spot Requests with Bid Status Codes in the Amazon Elastic Compute Cloud User Guide.

Type: String

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

status-code

The short code describing the most recent evaluation of your Spot Instance request. For more information, see Spot Bid Status in the Amazon Elastic Compute Cloud User Guide.

Type: String

status-message

The message explaining the status of the Spot Instance request.

Type: String

tag-key

The 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 is X, see the tag:key filter.

For more information about tags, see Tagging Your Resources in the Amazon Elastic Compute Cloud User Guide.

Type: String

tag-value

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

Type: String

tag:key

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

Example: To list just the resources that have been assigned tag Purpose=X, specify:

Filter.1.Name=tag:Purpose

Filter.1.Value.1=X

Example: To list just resources that have been assigned tag Purpose=X OR Purpose=Y, specify:

Filter.1.Name=tag:Purpose

Filter.1.Value.1=X

Filter.1.Value.2=Y

type

The 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-from

The start date of the request.

Type: DateTime

valid-until

The end date of the request.

Type: DateTime

Response Elements

The following elements are returned in a DescribeSpotInstanceRequestsResponse element.

requestId

The ID of the request.

Type: xsd:string

spotInstanceRequestSet

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

Type: SpotInstanceRequestSetItemType

networkInterfaceSet

Information about the network interface.

Type: InstanceNetworkInterfaceSetItemRequestType

Examples

Example Request

This example returns information about current Spot Instance requests.

Example Response

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.

Find Running Spot Instances

You can use DescribeSpotInstanceRequests to find a running Spot Instance by examining the response. If the status of the Spot Instance is fulfilled, the instanceId will appear in the response and contain the identifier of the instance.

Alternatively, you can use DescribeInstances and use a filter to look for instances where instanceLifecycle contains spot. The following is an example request.

The following is an example response.

Document Conventions« PreviousNext »
Terms of UseDid this page help you?  Yes | No |  Tell us about it...