Amazon Elastic Compute Cloud
API Reference (API Version 2016-11-15)

Making API Requests

We provide the Query API for Amazon EC2, as well as software development kits (SDK) for Amazon Web Services (AWS) that enable you to access Amazon EC2 from your preferred programming language.

To monitor the calls made to the Amazon EC2 API for your account, including calls made by the AWS Management Console, command line tools, and other services, use AWS CloudTrail. For more information, see the AWS CloudTrail User Guide.

Required Knowledge

If you plan to access Amazon EC2 through an API, you should be familiar with the following:

  • XML

  • Web services

  • HTTP requests

  • One or more programming languages, such as Java, PHP, Perl, Python, Ruby, C#, or C++.

Available APIs for Amazon EC2

The Amazon EC2 Query API provides HTTP or HTTPS requests that use the HTTP verb GET or POST and a Query parameter named Action.

AWS provides libraries, sample code, tutorials, and other resources for software developers who prefer to build applications using language-specific APIs instead of submitting a request over HTTP or HTTPS. These libraries provide basic functions that automatically take care of tasks such as cryptographically signing your requests, retrying requests, and handling error responses, so that it is easier for you to get started.

For more information about downloading the AWS SDKs, see AWS SDKs and Tools. For more information about the language-specific APIs for Amazon EC2, see the following documentation.

AWS SDK for JavaScript

AWS SDK for Python

AWS SDK for Ruby



On this page:

  • Required Knowledge
  • Available APIs for Amazon EC2
  • Query Requests Build applications using language-specific API libraries, sample code, and tutorials provided by AWS. Query requests are HTTP or HTTPS requests that use the HTTP verb GET or POST and a Query parameter named Action. For a list of Amazon EC2 API actions, see Actions.
  • Structure of a GET Request
  • Endpoints
  • Query Parameters
  • Query API Authentication
  • Query Response Structures
  • Troubleshooting API Request Errors Troubleshoot errors using the error codes you receive from Amazon EC2. In the Amazon EC2 Query API, errors codes are indicated as being either client or server. Client errors usually occur because there is a problem with the structure, content, or validity of the request. Server errors usually indicate a server-side issue. For more information about API error codes, see Error Codes.
  • Query API Request Rate
  • Eventual Consistency
  • Unauthorized Operation
  • Ensuring Idempotency Ensure that your request is idempotent so that your requests complete only once. An idempotent operation completes no more than one time. When you launch an instance, the request typically returns before the operation has completed. You determine whether the operation was successful by monitoring the state of the instance (it goes from pending to running). If the operation times out or there are connection issues, you might need to retry the request. However, if the original request and a retry are both successful, you'll end up with more instances than you intended to launch. If you launch your instance using run-instances (AWS CLI), ec2-run-instances (Amazon EC2 CLI), or RunInstances, you can optionally provide a client token to ensure that the request is idempotent. If you repeat a request, the same response is returned for each repeated request. The only information that might vary in the response is the state of the instance. Contents
  • Client Tokens
  • Idempotency Support
  • Example Idempotent Command
  • Example Idempotent Query
  • SOAP Requests Replace any SOAP requests for Amazon EC2 as we have deprecated them. We have deprecated the SOAP API for Amazon EC2. After 1 December 2015, we will no longer support SOAP requests for any API versions, including versions 2014-02-01 and earlier. If you use a SOAP request against a later API version or after 1 December 2015, you will receive the following response: Client.UnsupportedProtocol: SOAP is no longer supported. Similarly, the AWS software development kits (SDKs) will no longer support SOAP requests after 1 December 2015 for any API version. If you are using the Amazon EC2 CLI tools, you can no longer use the EC2_PRIVATE_KEY and EC2_CERT environment variables. You must use the AWS_ACCESS_KEY and AWS_SECRET_KEY variables instead. For more information, see Setting Up the Amazon EC2 CLI and AMI Tools. We recommend that you use the Query API for Amazon EC2, or the SDKs for AWS. For more information, see . Cross-Origin Resource Sharing SupportCORS Support Use the Amazon EC2 API CORS support to build client-side web applications that can interact with the EC2 API. The Amazon EC2 API supports cross-origin resource sharing (CORS). CORS defines a way for client web applications that are loaded in one domain to interact with resources in a different domain. For more information, go to the Cross-Origin Resource Sharing W3C Recommendation. With CORS support for Amazon EC2, you can build rich client-side web applications that leverage the Amazon EC2 API. For example, suppose you are hosting a web site,, and you want to use JavaScript on your web pages to make requests to the Amazon EC2 API. Normally, a browser blocks JavaScript from allowing these requests, but with CORS, you are able to make cross-origin Amazon EC2 API calls from CORS is already enabled for the Amazon EC2 API, and is ready for you to use. You do not need to perform any additional configuration steps to start using this feature. There is no change to the way that you make calls to the Amazon EC2 API; they must still be signed with valid AWS credentials to ensure that AWS can authenticate the requestor. For more information, see Signing AWS API Requests in the Amazon Web Services General Reference. The implementation of CORS in the Amazon EC2 API is standardized. Your application can send a simple request to the Amazon EC2 API, or, depending on the content of the request, a preflight request followed by an actual request. Amazon EC2 allows the request from any origin For more information about CORS and examples of how it works, go to the following article on the Mozilla Developer Network: HTTP access control (CORS).
  • Simple/Actual Requests
  • Preflight Requests
  • Logging API Calls Using AWS CloudTrailLogging API Calls Use CloudTrail to log your API calls. Amazon EC2, Amazon EBS, and Amazon VPC are integrated with AWS CloudTrail, a service that captures API calls and delivers the log files to an Amazon S3 bucket that you specify. The API calls can be made indirectly by using the console, or directly by using a client such as the Amazon EC2 CLI, the AWS CLI, or the AWS SDKs. Using the information collected by CloudTrail, you can determine what request was made, the source IP address from which the request was made, who made the request, when it was made, and so on. To learn more about CloudTrail, including how to configure and enable it, see the AWS CloudTrail User Guide.
  • Amazon EC2, Amazon EBS, and Amazon VPC Information in CloudTrail
  • Understanding Amazon EC2, Amazon EBS, and Amazon VPC Log File Entries
  • VM Import Manifest The import manifest is an XML file created by the ec2-import-instance CLI command or AWS Management Portal for vCenter and consumed by the Amazon EC2 API operations ImportInstance or ImportVolume, or by the ec2-import-volume CLI command. The manifest allows a virtual machine image to be broken into small parts for transfer and then reassembled at the destination, with support for retrying failed partial transfers. This file is normally created, consumed, and destroyed by the Amazon EC2 tools without user intervention. In some exceptional situations, developers may wish to construct a manifest manually or programmatically, making it possible to bypass certain API operations while still providing a manifest for other operations that require the file as a parameter value. This topic documents the structure of the manifest and provides a sample file. Direct manipulation of the manifest departs from the standard workflow of the Amazon EC2 API and CLI. In general, we recommend that you follow the procedures in Importing and Exporting Instances when importing VM images.
  • Manifest Schema
  • Examples