DescribeTags - Amazon Elastic Compute Cloud

DescribeTags

Describes the specified tags for your EC2 resources.

For more information about tags, see Tag your Amazon EC2 resources in the Amazon Elastic Compute Cloud User Guide.

Important

We strongly recommend using only paginated requests. Unpaginated requests are susceptible to throttling and timeouts.

Note

The order of the elements in the response, including those within nested structures, might vary. Applications should not assume the elements appear in a particular order.

Request Parameters

The following parameters are for this specific action. For more information about required and optional parameters that are common to all actions, see Common Query Parameters.

DryRun

Checks whether you have the required permissions for the action, without actually making the request, and provides an error response. If you have the required permissions, the error response is DryRunOperation. Otherwise, it is UnauthorizedOperation.

Type: Boolean

Required: No

Filter.N

The filters.

  • key - The tag key.

  • resource-id - The ID of the resource.

  • resource-type - The resource type. For a list of possible values, see TagSpecification.

  • tag:<key> - The key/value combination of the tag. For example, specify "tag:Owner" for the filter name and "TeamA" for the filter value to find resources with the tag "Owner=TeamA".

  • value - The tag value.

Type: Array of Filter objects

Required: No

MaxResults

The maximum number of items to return for this request. This value can be between 5 and 1000. To get the next page of items, make another request with the token returned in the output. For more information, see Pagination.

Type: Integer

Required: No

NextToken

The token returned from a previous paginated request. Pagination continues from the end of the items returned by the previous request.

Type: String

Required: No

Response Elements

The following elements are returned by the service.

nextToken

The token to include in another request to get the next page of items. This value is null when there are no more items to return.

Type: String

requestId

The ID of the request.

Type: String

tagSet

The tags.

Type: Array of TagDescription objects

Errors

For information about the errors that are common to all actions, see Common client error codes.

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/2016-11-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-1234567890abcdef0</resourceId> <resourceType>instance</resourceType> <key>webserver</key> <value/> </item> <item> <resourceId>i-1234567890abcdef0</resourceId> <resourceType>instance</resourceType> <key>stack</key> <value>Production</value> </item> <item> <resourceId>i-0598c7d356eba48d7</resourceId> <resourceType>instance</resourceType> <key>database_server</key> <value/> </item> <item> <resourceId>i-0598c7d356eba48d7</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/2016-11-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

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/2016-11-15/"/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <tagSet> <item> <resourceId>i-0598c7d356eba48d7</resourceId> <resourceType>instance</resourceType> <key>webserver</key> <value/> </item> <item> <resourceId>i-0598c7d356eba48d7</resourceId> <resourceType>instance</resourceType> <key>stack</key> <value>Production</value> </item> <item> <resourceId>i-1234567890abcdef0</resourceId> <resourceType>instance</resourceType> <key>database_server</key> <value/> </item> <item> <resourceId>i-1234567890abcdef0</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. 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/2016-11-15/"/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <tagSet> <item> <resourceId>i-1234567890abcdef0</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/2016-11-15/"/"> <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId> <tagSet> <item> <resourceId>i-1234567890abcdef0</resourceId> <resourceType>instance</resourceType> <key>stack</key> <value>Production</value> </item> <item> <resourceId>i-0598c7d356eba48d7</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

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: