Query requests are HTTP or HTTPS requests that use the HTTP verb GET or POST and aQuery parameter namedAction. For each Amazon EC2 API action, you can choose whether to use GET or POST. Regardless of which verb you choose, the same data is sent and received. For a list of Amazon EC2 API actions, seeActions.

Structure of a GET request

The Amazon EC2 documentation presents the GET requests as URLs, which can be useddirectly in a browser.

The request consists of the following:

The following optional parameters can be included in your request:

For more information about common parameters for API requests, seeCommon query parameters.

The following is an example request that launches instances:

https://ec2.amazonaws.com/?Action=RunInstances&ImageId=ami-2bb65342&MaxCount=3&MinCount=1&Placement.AvailabilityZone=us-east-1a&Monitoring.Enabled=true&Version=2016-11-15&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIDEXAMPLE%2F20130813%2Fus-east-1%2Fec2%2Faws4_request&X-Amz-Date=20130813T150206Z&X-Amz-SignedHeaders=content-type%3Bhost%3Bx-amz-date&X-Amz-Signature=525d1a96c69b5549dd78dbbec8efe264102288b83ba87b7d58d4b76b71f59fd2Content-type: application/jsonhost:ec2.amazonaws.com

To make these example requests even easier to read, AWS documentation may present them inthe following format:

https://ec2.amazonaws.com/?Action=RunInstances&ImageId=ami-2bb65342&MaxCount=3&MinCount=1&Placement.AvailabilityZone=us-east-1a&Monitoring.Enabled=true&Version=2016-11-15&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIOSFODNN7EXAMPLEus-east-1%2Fec2%2Faws4_request&X-Amz-Date=20130813T150206Z&X-Amz-SignedHeaders=content-type%3Bhost%3Bx-amz-date&X-Amz-Signature=ced6826de92d2bdeed8f846f0bf508e8559e98e4b0194b84example54174deb456cContent-type: application/jsonhost:ec2.amazonaws.com

The first line specifies the endpoint of the request. After the endpoint is aquestion mark (?), which separates the endpoint from the parameters. For more informationabout Amazon EC2 endpoints, seeAmazon EC2 service endpoints.

TheAction parameter indicates the action to perform. For a complete list ofactions, seeActions. Theremaining lines specify additional parameters for the request.

In the example Query requests we present in the Amazon EC2 API documentation, we omit theheaders,common required parameters, andauthentication parameters to make it easier for you to focus on the parameters forthe action. We replace them with the&AUTHPARAMS literal string toremind you that you must include these parameters in your request; forexample:

https://ec2.amazonaws.com/?Action=RunInstances&ImageId=ami-2bb65342&MaxCount=3&MinCount=1&Placement.AvailabilityZone=us-east-1a&Monitoring.Enabled=true&AUTHPARAMS

Query parameters

Each Query request must include required common parameters to handle authentication andselection of an action. Query parameters are case sensitive.

Some operations take lists of parameters. These lists are specified using theparam.n notation, wheren is aninteger starting from 1.

The following example adds multiple devices to a block device mapping using a listofBlockDeviceMapping parameters.

http://ec2.amazonaws.com/?Action=RunInstances&ImageId.1=ami-72aa081b...&BlockDeviceMapping.1.DeviceName=/dev/sdj&BlockDeviceMapping.1.Ebs.NoDevice=true&BlockDeviceMapping.2.DeviceName=/dev/sdh&BlockDeviceMapping.2.Ebs.VolumeSize=300&BlockDeviceMapping.3.DeviceName=/dev/sdc&BlockDeviceMapping.3.VirtualName=ephemeral1&AUTHPARAMS

Query API authentication

You can send Query requests over either the HTTP or HTTPS protocol.

Regardless of which protocol you use, you must include a signature in every Query request.Amazon EC2 supports Signature Version 2 and Signature Version 4. We recommend that you use Signature Version 4. For more information, seeSigning AWS API requests in theIAM User Guide.

Signature Version 4 requests allow you to specify all the authorization parameters in asingle header, for example:

Content-Type: application/x-www-form-urlencoded; charset=UTF-8X-Amz-Date: 20130813T150211ZHost: ec2.amazonaws.comAuthorization: AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/202230813/us-east-1/ec2/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=ced6826de92d2bdeed8f846f0bf508e8559e98e4b0194b84example54174deb456chttp://ec2.amazonaws.com/?Action=RunInstancesImageId=ami-2bb65342&MaxCount=3&MinCount=1&Monitoring.Enabled=true&Placement.AvailabilityZone=us-east-1a&Version=2016-11-15

Query response structures

In response to a Query request, the service returns an XML data structure that conforms toan XML schema defined for Amazon EC2. The structure of an XML response is specific to theassociated request. In general, the response data types are named according to the operationperformed and whether the data type is a container (can have children). Examples ofcontainers includegroupSet for security groups andkeySet for keypairs (see the example that follows). Item elements are children of containers, and theircontents vary according to the container's role.

Every successful response includes a request ID in arequestId element, andevery unsuccessful response includes a request ID in aRequestIDelement. The value is a unique string that AWS assigns. If you ever have issues witha particular request, AWS will ask for the request ID to help troubleshoot theissue. The following shows an example response.

<DescribeKeyPairsResponse xmlns="http://ec2.amazonaws.com/doc/2016-11-15/">  <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId>  <keySet>    <item>      <keyName>gsg-keypair</keyName>      <keyFingerprint>         00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00      </keyFingerprint>    </item>  </keySet></DescribeKeyPairsResponse>

Pagination

For actions that can return a long list of items, the Amazon EC2 API includes parameters to support pagination:MaxResults,NextToken (input), andnextToken (output). With pagination, you specify a size forMaxResults and then each call returns 0 toMaxResults items and setsnextToken. If there are additional items to iterate,nextToken is non-null and you can specify its value in theNextToken parameter of a subsequent call to get the next set of items. With pagination, you continue to call the action untilnextToken is null, even if you receive less thanMaxResults items, including zero items.

If you call a describe API action with both a list of IDs andMaxResults, the request fails with the errorInvalidParameterCombination.

We recommend that you use pagination when using describe actions that can potentially return a large number of results, such asDescribeInstances. Using pagination bounds the number of items returned and the time it takes for these calls to return.

For more information, seePagination in theAmazon EC2 Developer Guide.

Preventing requests over HTTP

If your workload does not require you to use HTTP, we recommend that you avoid using it to prevent transmitting and receiving unencrypted data, and to use HTTPS instead. You can use theaws:SecureTransport global IAM condition key in your IAM policies to prevent users from sending requests over HTTP.

The following example policy prevents users from sending requests over HTTP.

{    "Statement": [{            "Sid": "AllowAllEC2HttpsRequests",            "Effect": "Allow",            "Action": "ec2:*",            "Resource": "*",            "Condition":{                "StringEqualsIgnoreCase":{                    "aws:SecureTransport": "true"                }            }        }    ]}

Thanks for letting us know we're doing a good job!

If you've got a moment, please tell us what we did right so we can do more of it.

Thanks for letting us know this page needs work. We're sorry we let you down.

If you've got a moment, please tell us how we can make the documentation better.