DescribeTags - Amazon Elastic Compute Cloud
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

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.

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 (customer-gateway | dedicated-host | dhcp-options | elastic-ip | fleet | fpga-image | host-reservation | image | instance | internet-gateway | key-pair | launch-template | natgateway | network-acl | network-interface | placement-group | reserved-instances | route-table | security-group | snapshot | spot-instances-request | subnet | volume | vpc | vpc-endpoint | vpc-endpoint-service | vpc-peering-connection | vpn-connection | vpn-gateway).

  • 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 Amazon SDKs, see the following: