Amazon Elastic Compute Cloud
API Reference (API Version 2013-02-01)
AWS Documentation » Amazon EC2 » API Reference » Actions » DescribeTags
« 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.

Request Parameters

Filter.n.Name

The name of a filter. See the Supported Filters section for a list of supported filter names.

Type: String

Default: None

Required: No

Filter.n.Value.m

A value for the filter. See the Supported Filters section for a list of supported values for each filter.

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

Examples

Example Request

This example describes all the tags in your account.

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

Sample response:

<DescribeTagsResponse xmlns="http://ec2.amazonaws.com/doc/2013-02-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 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

Sample response:

<DescribeTagsResponse xmlns="http://ec2.amazonaws.com/doc/2013-02-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 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

Sample response:

<DescribeTagsResponse xmlns="http://ec2.amazonaws.com/doc/2013-02-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 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

Sample response:

<DescribeTagsResponse xmlns="http://ec2.amazonaws.com/doc/2013-02-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 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

Sample response:

<DescribeTagsResponse xmlns="http://ec2.amazonaws.com/doc/2013-02-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 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
Document Conventions« PreviousNext »
Terms of UseDid this page help you?  Yes | No |  Tell us about it...