Amazon Elastic Compute Cloud
API Reference (API Version 2015-03-01)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.

DescribeTags

Describes one or more of the tags for your EC2 resources.

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

Request Parameters

For information about the common parameters that all actions use, see Common Query Parameters.

DryRun

Type: Boolean

Required: No

Filter.N

One or more filters.

  • key - The tag key.

  • resource-id - The resource ID.

  • resource-type - The resource type (customer-gateway | dhcp-options | image | instance | internet-gateway | network-acl | network-interface | reserved-instances | route-table | security-group | snapshot | spot-instances-request | subnet | volume | vpc | vpn-connection | vpn-gateway).

  • value - The tag value.

Type: Filter list

Required: No

MaxResults

The maximum number of results to return for the request in a single page. The remaining results of the initial request can be seen by sending another request with the returned NextToken value. This value can be between 5 and 1000; if MaxResults is given a value larger than 1000, only 1000 results are returned.

Type: Integer

Required: No

NextToken

The token to retrieve the next page of results.

Type: String

Required: No

Response Elements

The following elements are returned.

nextToken

The token to use to retrieve the next page of results. This value is null when there are no more results to return..

Type: String

requestId

The ID of the request.

Type: String

tagSet

A list of tags.

Type: TagDescription list

Errors

For information about the errors that are common to all actions, see Common Client Errors.

Examples

Example

This example describes all the tags in your account.

Sample Request

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

Sample Response

<DescribeTagsResponse xmlns="http://ec2.amazonaws.com/doc/2014-10-01/"/">
   <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId>
   <tagSet>
      <item>
         <resourceId>ami-1a2b3c4d</resourceId>
         <resourceType>image</resourceType>
         <key>webserver</key>
         <value/>
      </item>
       <item>
         <resourceId>ami-1a2b3c4d</resourceId>
         <resourceType>image</resourceType>
         <key>stack</key>
         <value>Production</value>
      </item>
      <item>
         <resourceId>i-5f4e3d2a</resourceId>
         <resourceType>instance</resourceType>
         <key>webserver</key>
         <value/>
      </item>
       <item>
         <resourceId>i-5f4e3d2a</resourceId>
         <resourceType>instance</resourceType>
         <key>stack</key>
         <value>Production</value>
      </item>
      <item>
         <resourceId>i-12345678</resourceId>
         <resourceType>instance</resourceType>
         <key>database_server</key>
         <value/>
      </item>
       <item> 
         <resourceId>i-12345678</resourceId>
         <resourceType>instance</resourceType>
         <key>stack</key>
         <value>Test</value>
      </item>
    </tagSet>
</DescribeTagsResponse>

Example

This example describes only the tags for the AMI with ID ami-1a2b3c4d.

Sample Request

https://ec2.amazonaws.com/?Action=DescribeTags
&Filter.1.Name=resource-id
&Filter.1.Value.1=ami-1a2b3c4d
&AUTHPARAMS

Sample Response

<DescribeTagsResponse xmlns="http://ec2.amazonaws.com/doc/2014-10-01/"/">
   <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId>
   <tagSet>
      <item>
         <resourceId>ami-1a2b3c4d</resourceId>
         <resourceType>image</resourceType>
         <key>webserver</key>
         <value/>
      </item>
      <item>
         <resourceId>ami-1a2b3c4d</resourceId>
         <resourceType>image</resourceType>
         <key>stack</key>
         <value>Production</value>
      </item>
    </tagSet>
</DescribeTagsResponse>

Example

This example describes the tags for all your instances.

Sample Request

https://ec2.amazonaws.com/?Action=DescribeTags
&Filter.1.Name=resource-type
&Filter.1.Value.1=instance
&AUTHPARAMS

Sample Response

<DescribeTagsResponse xmlns="http://ec2.amazonaws.com/doc/2014-10-01/"/">
   <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId>
   <tagSet>
       <item>
         <resourceId>i-5f4e3d2a</resourceId>
         <resourceType>instance</resourceType>
         <key>webserver</key>
         <value/>
      </item>
       <item>
         <resourceId>i-5f4e3d2a</resourceId>
         <resourceType>instance</resourceType>
         <key>stack</key>
         <value>Production</value>
      </item>
      <item>
         <resourceId>i-12345678</resourceId>
         <resourceType>instance</resourceType>
         <key>database_server</key>
         <value/>
      </item>
       <item>
         <resourceId>i-12345678</resourceId>
         <resourceType>instance</resourceType>
         <key>stack</key>
         <value>Test</value>
      </item>
    </tagSet>
</DescribeTagsResponse>

Example

This example describes the tags for all your instances tagged with the key webserver. Note that you can use wildcards with filters, so you could specify the value as ?ebserver to find tags with the key webserver or Webserver.

Sample Request

https://ec2.amazonaws.com/?Action=DescribeTags
&Filter.1.Name=key
&Filter.1.Value.1=webserver
&AUTHPARAMS

Sample Response

<DescribeTagsResponse xmlns="http://ec2.amazonaws.com/doc/2014-10-01/"/">
   <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId>
   <tagSet>
       <item>
         <resourceId>i-5f4e3d2a</resourceId>
         <resourceType>instance</resourceType>
         <key>webserver</key>
         <value/>
      </item>
    </tagSet>
</DescribeTagsResponse>

Example

This example describes the tags for all your instances tagged with either stack=Test or stack=Production.

Sample Request

https://ec2.amazonaws.com/?Action=DescribeTags
&Filter.1.Name=resource-type
&Filter.1.Value.1=instance
&Filter.2.Name=key
&Filter.2.Value.1=stack
&Filter.3.Name=value
&Filter.3.Value.1=Test
&Filter.3.Value.2=Production
&AUTHPARAMS

Sample Response

<DescribeTagsResponse xmlns="http://ec2.amazonaws.com/doc/2014-10-01/"/">
   <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId>   
   <tagSet>
       <item>
         <resourceId>i-5f4e3d2a</resourceId>
         <resourceType>instance</resourceType>
         <key>stack</key>
         <value>Production</value>
      </item>
       <item>
         <resourceId>i-12345678</resourceId>
         <resourceType>instance</resourceType>
         <key>stack</key>
         <value>Test</value>
      </item>
    </tagSet>
</DescribeTagsResponse>

Example

This example describes the tags for all your instances tagged with Purpose=[empty string].

Sample Request

https://ec2.amazonaws.com/?Action=DescribeTags
&Filter.1.Name=resource-type
&Filter.1.Value.1=instance
&Filter.2.Name=key
&Filter.2.Value.1=Purpose
&Filter.3.Name=value
&Filter.3.Value.1=
&AUTHPARAMS