A Quick Guide to the AWS Spot Instance API

Posted in

Amazon Web Services (AWS) is the world’s largest cloud provider. At the core of Amazon’s services is the Elastic Compute Cloud (EC2), which provides virtual machines called “compute instances” on an on-demand basis, billed by the second.

As organizations move to the cloud, cloud costs are becoming a concern for any development or IT project. Thus, there is a growing interest in spot instances, which grant a discount of up to 90% (you read it right) on Amazon’s regular on-demand per-hour cost.

Spot instances are Amazon’s mechanism for selling spare capacity. Essentially, they are unused compute instances AWS is prepared to sell at a major discount. The catch is that if the price goes up above your bid, the instances are terminated with two minutes’ notice. This means that, to leverage spot instances, users must put automation in place to control these cloud machines programmatically.

In this article, we’ll introduce spot instances and how to work with the spot instance API. This is an essential API for any organization that leverages the Amazon cloud, because it can uncover dramatic savings in cloud costs.

How Spot Instances Work

AWS spot instance pricing is determined according to supply and demand trends on the EC2 spot market. The system charges for spot instances according to the spot price at the beginning of the instance hour. Billing is rounded to the nearest second.

Spot instances let you pay less or precisely the maximum price you define. When the spot instance price goes above your maximum price or capacity is unavailable, your instance will be terminated automatically. Another alternative is stopping or hibernating your instance, but you need to enable this option.

After terminating a spot instance, the system bills you for any partial hour used. There is one exception, though. If a spot price exceeds the maximum price and the spot instance is interrupted, EC2 does not charge for a partial hour of usage. For more details, see this in-depth post on AWS spot instances.

AWS Spot Fleets

AWS Spot Fleets are collections of spot instances offered at a discounted price. Spot Fleets automatically respond to events and poll instances. Applications can make Spot Fleets requests via the Spot Fleet API or using the command-line interface (CLI).

Users can request a Spot Fleet by defining the maximum target price for each instance hour and the desired capacity, as well as instance types, the number of required instances, and availability zones.

Pricing for spot instances changes constantly, and EC2 tries to maintain Spot Fleet capacity according to the predefined targets. Once prices exceed user-defined limits, EC2 terminates spot instances and launches replacement instances offered at the lowest available price.

AWS automates the management of Spot Fleets, and requests remain active until they are canceled. However, when you cancel a spot fleet request, you do not shut down individual spot instances. To enable AWS to terminate instances automatically, you’ll need to define a relevant Identity and Access Management (IAM) role for Spot Fleet.

AWS Spot Fleet is typically used in tandem with the AWS Auto Scaling service, which can automatically scale EC2 instances up and down based on predefined schedules or application loads as reported by AWS monitoring tools.

Using the Spot Instance API

Let’s dive into how the spot instance API works. Our examples are based on code from the Amazon spot instance API documentation.


To access EC2 via an API, you need to be familiar with Extensible Markup Language (XML), HTTP requests, and web services. You should also be familiar with one or more programming languages, like Java, Python, PHP, C++, Perl, Ruby, and C#.

The EC2 Query API uses HTTP/S requests with either GET or POST. The Query parameter is named Action.

Request Structure

Requests for EC2 and spot instances are composed of the following:

  • Endpoint: A URL serving as an entry point for a web service.
  • Action: An action to perform. For example, using RunInstances to launch your instance.
  • Parameters: For your action. You must separate each parameter by using an ampersand (&).
  • Version: An API version you can use.
  • Authorization parameters: Used by AWS to validate and authenticate each request.

Here are optional parameters you can include in your requests:

  • DryRun: Checks if you have the permissions needed to perform the action. This check is made without making the request. If users have the required permission, the request will return DryRunOperation. Otherwise, the request will return UnauthorizedOperation.
  • SecurityToken A temporary security token that you can obtain via a call to the AWS Security Token Service.

Creating a Spot Instance

Let’s see how to create a spot instance request with the following parameters:

  • One-time request, so instances are not replenished if they fail.
  • Request for two instances.
  • Instance type is m3.medium (see all Amazon instance types).
  • Instances will be created in a specific availability zone: US West 2A. This also affects pricing — the spot price will be determined according to the availability of this type of instance in that particular availability zone.
  • The request provides the following additional information:
    • ID of the Amazon Machine Image (the image that will be used to run the instance)
    • Key pair for authentication
    • ID of the security group the instances should belong to
    • Profile name in Amazon Identity and Access Management (IAM), defining the level of access the instances will have to Amazon resources

The request looks like this:


If the request does not explicitly request an availability zone (AZ), Amazon automatically selects one.

Creating a Spot Fleet Request

A Spot Fleet request is a dynamic request that specifies a group of compute instances, which may include both spot and regular on-demand instances.

Combining spot and on-demand instances is an important strategy — it allows you “reserve” some capacity even in case spot instances will be terminated because of pricing or availability. To learn about mixing spot and on-demand instances, see the documentation.

Here is how to create a simple Spot Fleet request that creates one or more spot instances. The request specifies the following parameters:

  • Target capacity: The total number of instances required.
  • Launch specifications: The request below provides two types of launch specifications, meaning Amazon can fulfill the request using two types of instances. Each launch request specifies:
    • Amazon Machine Image (AMI) ID
    • Instance type
    • Subnet in which the instances should run

Here is what the request looks like:


The response includes a link to an XML document that details how the request was fulfilled.


In this post, we introduced the concept of AWS spot instances and demonstrated how they could be managed at scale using the AWS Spot Fleet service. Finally, we showed how to take your first steps with the AWS spot instance API:

  • Setting up the API and understanding request/response structure
  • Creating an instance with a one-time request
  • Creating a spot fleet that creates multiple spot instances and replenishes them according to predefined conditions

Outside of AWS, GCP and Azure also offer comparable spot instance functionalities. We hope this knowledge will help you leverage the power of spot instances to begin saving on cloud costs for your organization.