Amazon Elastic Compute Cloud
API Reference (API Version 2014-06-15)
« 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...

DescribeTags

Description

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 for Linux.

Request Parameters

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

MaxResults

The maximum number of items to return for this call. The call also returns a token that you can specify in a subsequent call to get the next set of results.

Type: Integer

Default: The call returns all items.

Constraint: If the value is greater than 1000, we return only 1000 items.

Required: No

NextToken

The token for the next set of items to return. (You received this token from a prior call.)

Type: String

Default: None

Required: No

Filter.n.Name

The name of a filter. Filter names are case-sensitive. For more information about supported filter names, see the Supported Filters section.

Type: String

Default: None

Required: No

Filter.n.Value.m

A value for the filter. Filter values are case-sensitive. For more information about supported values for each filter, see the Supported Filters section.

Type: String

Default: None

Required: No

Supported Filters

You can specify filters to limit the response when describing tags. For example, you can use a filter to get only the tags for a specific resource type. You can specify multiple values for a filter. The response includes information for a tag only if it matches at least one of the filter values that you specified.

You can specify multiple filters (for example, specify a specific resource type and tag values that contain the string database). The response includes information for a tag 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.

key

The tag key.

Type: String

resource-id

The resource ID.

Type: String

resource-type

The resource type.

Type: String

Valid values: 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: String

Response Elements

The following elements are returned in a DescribeTagsResponse element.

requestId

The ID of the request.

Type: xsd:string

tagSet

A list of tags. Each tag is wrapped in an item element.

Type: TagSetItemType

nextToken

The token to use when requesting the next set of items. If there are no additional items to return, the string is empty.

Type: xsd:string

Examples

Example Request

This example describes all the tags in your account.

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

Example Response

<DescribeTagsResponse xmlns="http://ec2.amazonaws.com/doc/2014-06-15/">
   <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 Request

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

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

Example Response

<DescribeTagsResponse xmlns="http://ec2.amazonaws.com/doc/2014-06-15/">
   <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 Request

This example describes the tags for all your instances.

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

Example Response

<DescribeTagsResponse xmlns="http://ec2.amazonaws.com/doc/2014-06-15/">
   <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 Request

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.

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

Example Response

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

Example Request

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

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

Example Response

<DescribeTagsResponse xmlns="http://ec2.amazonaws.com/doc/2014-06-15/">
   <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 Request

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

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