Resource Groups Tagging API

API Reference
API Version 2017-01-26
 Resource Groups Tagging API API Reference

Resource Groups Tagging API: API Reference

Copyright © 2020 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not
Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or
discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may
or may not be affiliated with, connected to, or sponsored by Amazon.
 Resource Groups Tagging API API Reference

Table of Contents
Welcome ........................................................................................................................................... 1
Actions ............................................................................................................................................. 4
DescribeReportCreation ............................................................................................................... 5
Response Syntax ................................................................................................................ 5
Response Elements ............................................................................................................. 5
Errors ............................................................................................................................... 5
Example ............................................................................................................................ 6
See Also ............................................................................................................................ 7
GetComplianceSummary ............................................................................................................. 8
Request Syntax .................................................................................................................. 8
Request Parameters ............................................................................................................ 8
Response Syntax .............................................................................................................. 10
Response Elements ........................................................................................................... 10
Errors .............................................................................................................................. 10
Example .......................................................................................................................... 11
See Also .......................................................................................................................... 12
GetResources ........................................................................................................................... 13
Request Syntax ................................................................................................................ 13
Request Parameters .......................................................................................................... 13
Response Syntax .............................................................................................................. 15
Response Elements ........................................................................................................... 16
Errors .............................................................................................................................. 16
Example .......................................................................................................................... 17
See Also .......................................................................................................................... 17
GetTagKeys .............................................................................................................................. 19
Request Syntax ................................................................................................................ 19
Request Parameters .......................................................................................................... 19
Response Syntax .............................................................................................................. 19
Response Elements ........................................................................................................... 19
Errors .............................................................................................................................. 20
Example .......................................................................................................................... 20
See Also .......................................................................................................................... 21
GetTagValues ........................................................................................................................... 22
Request Syntax ................................................................................................................ 22
Request Parameters .......................................................................................................... 22
Response Syntax .............................................................................................................. 22
Response Elements ........................................................................................................... 22
Errors .............................................................................................................................. 23
Example .......................................................................................................................... 24
See Also .......................................................................................................................... 24
StartReportCreation .................................................................................................................. 25
Request Syntax ................................................................................................................ 25
Request Parameters .......................................................................................................... 25
Response Elements ........................................................................................................... 25
Errors .............................................................................................................................. 25
Examples ......................................................................................................................... 26
See Also .......................................................................................................................... 27
TagResources ........................................................................................................................... 29
Request Syntax ................................................................................................................ 29
Request Parameters .......................................................................................................... 29
Response Syntax .............................................................................................................. 30
Response Elements ........................................................................................................... 30
Errors .............................................................................................................................. 30
Example .......................................................................................................................... 31

API Version 2017-01-26

iii
 Resource Groups Tagging API API Reference

See Also .......................................................................................................................... 31

UntagResources ........................................................................................................................ 33
Request Syntax ................................................................................................................ 33
Request Parameters .......................................................................................................... 33
Response Syntax .............................................................................................................. 34
Response Elements ........................................................................................................... 34
Errors .............................................................................................................................. 34
Example .......................................................................................................................... 35
See Also .......................................................................................................................... 35
Data Types ...................................................................................................................................... 37
ComplianceDetails .................................................................................................................... 38
Contents ......................................................................................................................... 38
See Also .......................................................................................................................... 38
FailureInfo ............................................................................................................................... 39
Contents ......................................................................................................................... 39
See Also .......................................................................................................................... 39
ResourceTagMapping ................................................................................................................ 41
Contents ......................................................................................................................... 41
See Also .......................................................................................................................... 41
Summary ................................................................................................................................ 42
Contents ......................................................................................................................... 42
See Also .......................................................................................................................... 43
Tag ......................................................................................................................................... 44
Contents ......................................................................................................................... 44
See Also .......................................................................................................................... 44
TagFilter .................................................................................................................................. 45
Contents ......................................................................................................................... 45
See Also .......................................................................................................................... 45
Common Parameters ........................................................................................................................ 46
Common Errors ................................................................................................................................ 48

API Version 2017-01-26

iv
 Resource Groups Tagging API API Reference

Welcome
This guide describes the API operations for the resource groups tagging.

A tag is a label that you assign to an AWS resource. A tag consists of a key and a value, both of which you
define. For example, if you have two Amazon EC2 instances, you might assign both a tag key of "Stack."
But the value of "Stack" might be "Testing" for one and "Production" for the other.

Tagging can help you organize your resources and enables you to simplify resource management, access
management and cost allocation.

You can use the resource groups tagging API operations to complete the following tasks:

• Tag and untag supported resources located in the specified Region for the AWS account.
• Use tag-based filters to search for resources located in the specified Region for the AWS account.
• List all existing tag keys in the specified Region for the AWS account.
• List all existing values for the specified key in the specified Region for the AWS account.

To use resource groups tagging API operations, you must add the following permissions to your IAM
policy:

• tag:GetResources
• tag:TagResources
• tag:UntagResources
• tag:GetTagKeys
• tag:GetTagValues

You'll also need permissions to access the resources of individual services so that you can tag and untag
those resources.

For more information on IAM policies, see Managing IAM Policies in the IAM User Guide.

You can use the Resource Groups Tagging API to tag resources for the following AWS services.

• Alexa for Business (a4b)

• API Gateway
• Amazon AppStream
• AWS AppSync
• AWS App Mesh
• Amazon Athena
• Amazon Aurora
• AWS Backup
• AWS Certificate Manager
• AWS Certificate Manager Private CA
• Amazon Cloud Directory
• AWS CloudFormation
• Amazon CloudFront
• AWS CloudHSM

API Version 2017-01-26

1
 Resource Groups Tagging API API Reference

• AWS CloudTrail
• Amazon CloudWatch (alarms only)
• Amazon CloudWatch Events
• Amazon CloudWatch Logs
• AWS CodeBuild
• AWS CodeCommit
• AWS CodePipeline
• AWS CodeStar
• Amazon Cognito Identity
• Amazon Cognito User Pools
• Amazon Comprehend
• AWS Config
• AWS Data Exchange
• AWS Data Pipeline
• AWS Database Migration Service
• AWS DataSync
• AWS Device Farm
• AWS Direct Connect
• AWS Directory Service
• Amazon DynamoDB
• Amazon EBS
• Amazon EC2
• Amazon ECR
• Amazon ECS
• Amazon EKS
• AWS Elastic Beanstalk
• Amazon Elastic File System
• Elastic Load Balancing
• Amazon ElastiCache
• Amazon Elasticsearch Service
• AWS Elemental MediaLive
• AWS Elemental MediaPackage
• AWS Elemental MediaTailor
• Amazon EMR
• Amazon FSx
• Amazon S3 Glacier
• AWS Glue
• Amazon GuardDuty
• Amazon Inspector
• AWS IoT Analytics
• AWS IoT Core
• AWS IoT Device Defender
• AWS IoT Device Management
• AWS IoT Events
• AWS IoT Greengrass
• AWS IoT 1-Click

API Version 2017-01-26

2
 Resource Groups Tagging API API Reference

• AWS Key Management Service

• Amazon Kinesis
• Amazon Kinesis Data Analytics
• Amazon Kinesis Data Firehose
• AWS Lambda
• AWS License Manager
• Amazon Machine Learning
• Amazon MQ
• Amazon MSK
• Amazon Neptune
• AWS OpsWorks
• AWS Organizations
• Amazon Quantum Ledger Database (QLDB)
• Amazon RDS
• Amazon Redshift
• AWS Resource Access Manager
• AWS Resource Groups
• AWS RoboMaker
• Amazon Route 53
• Amazon Route 53 Resolver
• Amazon S3 (buckets only)
• Amazon SageMaker
• AWS Secrets Manager
• AWS Security Hub
• AWS Service Catalog
• Amazon Simple Notification Service (SNS)
• Amazon Simple Queue Service (SQS)
• Amazon Simple Workflow Service
• AWS Step Functions
• AWS Storage Gateway
• AWS Systems Manager
• AWS Transfer for SFTP
• Amazon VPC
• Amazon WorkSpaces

This document was last published on February 4, 2020.

API Version 2017-01-26

3
 Resource Groups Tagging API API Reference

Actions
The following actions are supported:

• DescribeReportCreation (p. 5)
• GetComplianceSummary (p. 8)
• GetResources (p. 13)
• GetTagKeys (p. 19)
• GetTagValues (p. 22)
• StartReportCreation (p. 25)
• TagResources (p. 29)
• UntagResources (p. 33)

API Version 2017-01-26

4
 Resource Groups Tagging API API Reference
DescribeReportCreation

DescribeReportCreation
Describes the status of the StartReportCreation operation.

You can call this operation only from the organization's master account and from the us-east-1 Region.

Response Syntax
{
"ErrorMessage": "string",
"S3Location": "string",
"Status": "string"
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

ErrorMessage (p. 5)

Details of the common errors that all operations return.

Type: String
S3Location (p. 5)

The path to the Amazon S3 bucket where the report was stored on creation.

Type: String
Status (p. 5)

Reports the status of the operation.

The operation status can be one of the following:

• RUNNING - Report creation is in progress.
• SUCCEEDED - Report creation is complete. You can open the report from the Amazon S3 bucket
that you specified when you ran StartReportCreation.
• FAILED - Report creation timed out or the Amazon S3 bucket is not accessible.
• NO REPORT - No report was generated in the last 90 days.

Type: String

Errors
For information about the errors that are common to all actions, see Common Errors (p. 48).

ConstraintViolationException

The request was denied because performing this operation violates a constraint.

Some of the reasons in the following list might not apply to this specific operation.
• You must meet the prerequisites for using tag policies. For information, see Prerequisites and
Permissions for Using Tag Policies in the AWS Organizations User Guide.

API Version 2017-01-26

5
 Resource Groups Tagging API API Reference
Example

• You must enable the tag policies service principal (tagpolicies.tag.amazonaws.com) to

integrate with AWS Organizations For information, see EnableAWSServiceAccess.
• You must have a tag policy attached to the organization root, an OU, or an account.

HTTP Status Code: 400

InternalServiceException

The request processing failed because of an unknown error, exception, or failure. You can retry the
request.

HTTP Status Code: 500

InvalidParameterException

This error indicates one of the following:

• A parameter is missing.
• A malformed string was supplied for the request parameter.
• An out-of-range value was supplied for the request parameter.
• The target ID is invalid, unsupported, or doesn't exist.
• You can't access the Amazon S3 bucket for report storage. For more information, see Additional
Requirements for Organization-wide Tag Compliance Reports in the AWS Organizations User
Guide.

HTTP Status Code: 400

ThrottledException

The request was denied to limit the frequency of submitted requests.

HTTP Status Code: 400

Example
Sample Request

POST / HTTP/1.1
Host: tagging.us-east-1.amazonaws.com
Accept-Encoding: identity
Content-Length: 20
X-Amz-Target: ResourceGroupsTaggingAPI_20170126.DescribeReportCreation
X-Amz-Date: 20191201T214524Z
User-Agent: aws-cli/1.11.79 Python/2.7.9 Windows/7 botocore/1.5.42
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS
{}

Sample Response

HTTP/1.1 200 OK
x-amzn-RequestID: d3cf21f0-26db-11e7-a532-75e05382c8b1
Content-Type: application/x-amz-json-1.1

API Version 2017-01-26

6
 Resource Groups Tagging API API Reference
See Also

Date: Sun, 1 Dec 2019 21:45:25 GMT

{
"ErrorMessage":null,
"S3Location":"s3://awsexamplebucket/AwsTagPolicies/o-
exampleorgid/2019-12-01-T21:45:24Z/report.csv",
"Status":"SUCCEEDED"
}

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

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2017-01-26

7
 Resource Groups Tagging API API Reference
GetComplianceSummary

GetComplianceSummary
Returns a table that shows counts of resources that are noncompliant with their tag policies.

For more information on tag policies, see Tag Policies in the AWS Organizations User Guide.

You can call this operation only from the organization's master account and from the us-east-1 Region.

Request Syntax
{
"GroupBy": [ "string" ],
"MaxResults": number,
"PaginationToken": "string",
"RegionFilters": [ "string" ],
"ResourceTypeFilters": [ "string" ],
"TagKeyFilters": [ "string" ],
"TargetIdFilters": [ "string" ]
}

Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 46).

The request accepts the following data in JSON format.

GroupBy (p. 8)

A list of attributes to group the counts of noncompliant resources by. If supplied, the counts are
sorted by those attributes.

Type: Array of strings

Valid Values: TARGET_ID | REGION | RESOURCE_TYPE

Required: No
MaxResults (p. 8)

A limit that restricts the number of results that are returned per page.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 1000.

Required: No
PaginationToken (p. 8)

A string that indicates that additional data is available. Leave this value empty for your initial
request. If the response includes a PaginationToken, use that string for this value to request an
additional page of data.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 2048.

Pattern: [\s\S]*

API Version 2017-01-26

8
 Resource Groups Tagging API API Reference
Request Parameters

Required: No
RegionFilters (p. 8)

A list of Regions to limit the output by. If you use this parameter, the count of returned
noncompliant resources includes only resources in the specified Regions.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 100 items.

Length Constraints: Minimum length of 1. Maximum length of 256.

Pattern: [\s\S]*

Required: No
ResourceTypeFilters (p. 8)

The constraints on the resources that you want returned. The format of each resource type is
service[:resourceType]. For example, specifying a resource type of ec2 returns all Amazon EC2
resources (which includes EC2 instances). Specifying a resource type of ec2:instance returns only
EC2 instances.

The string for each service name and resource type is the same as that embedded in a resource's
Amazon Resource Name (ARN). Consult the AWS General Reference for the following:
• For a list of service name strings, see AWS Service Namespaces.
• For resource type strings, see Example ARNs.
• For more information about ARNs, see Amazon Resource Names (ARNs) and AWS Service
Namespaces.

You can specify multiple resource types by using an array. The array can include up to 100 items.
Note that the length constraint requirement applies to each resource type filter.

Type: Array of strings

Length Constraints: Minimum length of 0. Maximum length of 256.

Pattern: [\s\S]*

Required: No
TagKeyFilters (p. 8)

A list of tag keys to limit the output by. If you use this parameter, the count of returned
noncompliant resources includes only resources that have the specified tag keys.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 50 items.

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [\s\S]*

Required: No
TargetIdFilters (p. 8)

The target identifiers (usually, specific account IDs) to limit the output by. If you use this parameter,
the count of returned noncompliant resources includes only resources with the specified target IDs.

Type: Array of strings

API Version 2017-01-26

9
 Resource Groups Tagging API API Reference
Response Syntax

Array Members: Minimum number of 1 item. Maximum number of 100 items.

Length Constraints: Minimum length of 6. Maximum length of 68.

Pattern: [\s\S]*

Required: No

Response Syntax
{
"PaginationToken": "string",
"SummaryList": [
{
"LastUpdated": "string",
"NonCompliantResources": number,
"Region": "string",
"ResourceType": "string",
"TargetId": "string",
"TargetIdType": "string"
}
]
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

PaginationToken (p. 10)

A string that indicates that the response contains more data than can be returned in a single
response. To receive additional data, specify this string for the PaginationToken value in a
subsequent request.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 2048.

Pattern: [\s\S]*
SummaryList (p. 10)

A table that shows counts of noncompliant resources.

Type: Array of Summary (p. 42) objects

Errors
For information about the errors that are common to all actions, see Common Errors (p. 48).

ConstraintViolationException

The request was denied because performing this operation violates a constraint.

Some of the reasons in the following list might not apply to this specific operation.

API Version 2017-01-26

10
 Resource Groups Tagging API API Reference
Example

• You must meet the prerequisites for using tag policies. For information, see Prerequisites and
Permissions for Using Tag Policies in the AWS Organizations User Guide.
• You must enable the tag policies service principal (tagpolicies.tag.amazonaws.com) to
integrate with AWS Organizations For information, see EnableAWSServiceAccess.
• You must have a tag policy attached to the organization root, an OU, or an account.

HTTP Status Code: 400

InternalServiceException

The request processing failed because of an unknown error, exception, or failure. You can retry the
request.

HTTP Status Code: 500

InvalidParameterException

This error indicates one of the following:

• A parameter is missing.
• A malformed string was supplied for the request parameter.
• An out-of-range value was supplied for the request parameter.
• The target ID is invalid, unsupported, or doesn't exist.
• You can't access the Amazon S3 bucket for report storage. For more information, see Additional
Requirements for Organization-wide Tag Compliance Reports in the AWS Organizations User
Guide.

HTTP Status Code: 400

ThrottledException

The request was denied to limit the frequency of submitted requests.

HTTP Status Code: 400

Example
Sample Request

HTTP/1.1
Host: tagging.us-east-1.amazonaws.com
Accept-Encoding: identity
Content-Length: 663
X-Amz-Target: ResourceGroupsTaggingAPI_20170126.GetComplianceSummary
X-Amz-Date: 20191201T214524Z
User-Agent: aws-cli/1.11.79 Python/2.7.9 Windows/7 botocore/1.5.42
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS
{
"GroupBy": [
"TARGET_ID",
"REGION",
"RESOURCE_TYPE"
]
}

API Version 2017-01-26

11
 Resource Groups Tagging API API Reference
See Also

Sample Response

HTTP/1.1 200 OK
x-amzn-RequestID: d3cf21f0-26db-11e7-a532-75e05382c8b1
Content-Type: application/x-amz-json-1.1
Date: Sun, 1 Dec 2019 21:45:25 GMT
{
"SummaryList": [
{
"LastUpdated":"2019-10-28T21:53:16Z",
"NonCompliantResources":1,
"Region":"us-east-1",
"ResourceType":"ec2:instance",
"TargetId":"333333333333",
"TargetIdType":"ACCOUNT"},
{
"LastUpdated":"2019-10-28T21:53:17Z",
"NonCompliantResources":0,
"Region":"us-east-1",
"ResourceType":"ec2:snapshot",
"TargetId":"222222222222",
"TargetIdType":"ACCOUNT"},
{
"LastUpdated":"2019-10-28T21:53:16Z",
"NonCompliantResources":1,
"Region":"us-east-1",
"ResourceType":"ec2:volume",
"TargetId":"111111111111",
"TargetIdType":"ACCOUNT"}
]
}
}

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

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2017-01-26

12
 Resource Groups Tagging API API Reference
GetResources

GetResources
Returns all the tagged or previously tagged resources that are located in the specified Region for the
AWS account.

Depending on what information you want returned, you can also specify the following:

• Filters that specify what tags and resource types you want returned. The response includes all tags that
are associated with the requested resources.
• Information about compliance with the account's effective tag policy. For more information on tag
policies, see Tag Policies in the AWS Organizations User Guide.

Note
You can check the PaginationToken response parameter to determine if a query is complete.
Queries occasionally return fewer results on a page than allowed. The PaginationToken
response parameter value is null only when there are no more results to display.

Request Syntax
{
"ExcludeCompliantResources": boolean,
"IncludeComplianceDetails": boolean,
"PaginationToken": "string",
"ResourcesPerPage": number,
"ResourceTypeFilters": [ "string" ],
"TagFilters": [
{
"Key": "string",
"Values": [ "string" ]
}
],
"TagsPerPage": number
}

Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 46).

The request accepts the following data in JSON format.

ExcludeCompliantResources (p. 13)

Specifies whether to exclude resources that are compliant with the tag policy. Set this to true if you
are interested in retrieving information on noncompliant resources only.

You can use this parameter only if the IncludeComplianceDetails parameter is also set to true.

Type: Boolean

Required: No
IncludeComplianceDetails (p. 13)

Specifies whether to include details regarding the compliance with the effective tag policy. Set this
to true to determine whether resources are compliant with the tag policy and to get details.

Type: Boolean

API Version 2017-01-26

13
 Resource Groups Tagging API API Reference
Request Parameters

Required: No
PaginationToken (p. 13)

A string that indicates that additional data is available. Leave this value empty for your initial
request. If the response includes a PaginationToken, use that string for this value to request an
additional page of data.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 2048.

Pattern: [\s\S]*

Required: No
ResourcesPerPage (p. 13)

A limit that restricts the number of resources returned by GetResources in paginated output. You can
set ResourcesPerPage to a minimum of 1 item and the maximum of 100 items.

Type: Integer

Required: No
ResourceTypeFilters (p. 13)

The constraints on the resources that you want returned. The format of each resource type is
service[:resourceType]. For example, specifying a resource type of ec2 returns all Amazon EC2
resources (which includes EC2 instances). Specifying a resource type of ec2:instance returns only
EC2 instances.

The string for each service name and resource type is the same as that embedded in a resource's
Amazon Resource Name (ARN). Consult the AWS General Reference for the following:
• For a list of service name strings, see AWS Service Namespaces.
• For resource type strings, see Example ARNs.
• For more information about ARNs, see Amazon Resource Names (ARNs) and AWS Service
Namespaces.

You can specify multiple resource types by using an array. The array can include up to 100 items.
Note that the length constraint requirement applies to each resource type filter.

Type: Array of strings

Length Constraints: Minimum length of 0. Maximum length of 256.

Pattern: [\s\S]*

Required: No
TagFilters (p. 13)

A list of TagFilters (keys and values). Each TagFilter specified must contain a key with values as
optional. A request can include up to 50 keys, and each key can include up to 20 values.

Note the following when deciding how to use TagFilters:

• If you do specify a TagFilter, the response returns only those resources that are currently
associated with the specified tag.
• If you don't specify a TagFilter, the response includes all resources that were ever associated with
tags. Resources that currently don't have associated tags are shown with an empty tag set, like
this: "Tags": [].

API Version 2017-01-26

14
 Resource Groups Tagging API API Reference
Response Syntax

• If you specify more than one filter in a single request, the response returns only those resources
that satisfy all specified filters.
• If you specify a filter that contains more than one value for a key, the response returns resources
that match any of the specified values for that key.
• If you don't specify any values for a key, the response returns resources that are tagged with that
key irrespective of the value.

For example, for filters: filter1 = {key1, {value1}}, filter2 = {key2, {value2,value3,value4}} , filter3 =
{key3}:
• GetResources( {filter1} ) returns resources tagged with key1=value1
• GetResources( {filter2} ) returns resources tagged with key2=value2 or key2=value3 or
key2=value4
• GetResources( {filter3} ) returns resources tagged with any tag containing key3 as its tag key,
irrespective of its value
• GetResources( {filter1,filter2,filter3} ) returns resources tagged with ( key1=value1) and
( key2=value2 or key2=value3 or key2=value4) and (key3, irrespective of the value)

Type: Array of TagFilter (p. 45) objects

Array Members: Minimum number of 0 items. Maximum number of 50 items.

Required: No
TagsPerPage (p. 13)

AWS recommends using ResourcesPerPage instead of this parameter.

A limit that restricts the number of tags (key and value pairs) returned by GetResources in paginated
output. A resource with no tags is counted as having one tag (one key and value pair).

GetResources does not split a resource and its associated tags across pages. If the specified
TagsPerPage would cause such a break, a PaginationToken is returned in place of the affected
resource and its tags. Use that token in another request to get the remaining data. For example, if
you specify a TagsPerPage of 100 and the account has 22 resources with 10 tags each (meaning
that each resource has 10 key and value pairs), the output will consist of three pages. The first page
displays the first 10 resources, each with its 10 tags. The second page displays the next 10 resources,
each with its 10 tags. The third page displays the remaining 2 resources, each with its 10 tags.

You can set TagsPerPage to a minimum of 100 items and the maximum of 500 items.

Type: Integer

Required: No

Response Syntax
{
"PaginationToken": "string",
"ResourceTagMappingList": [
{
"ComplianceDetails": {
"ComplianceStatus": boolean,
"KeysWithNoncompliantValues": [ "string" ],
"NoncompliantKeys": [ "string" ]
},
"ResourceARN": "string",
"Tags": [
{

API Version 2017-01-26

15
 Resource Groups Tagging API API Reference
Response Elements

"Key": "string",
"Value": "string"
}
]
}
]
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

PaginationToken (p. 15)

A string that indicates that the response contains more data than can be returned in a single
response. To receive additional data, specify this string for the PaginationToken value in a
subsequent request.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 2048.

Pattern: [\s\S]*
ResourceTagMappingList (p. 15)

A list of resource ARNs and the tags (keys and values) associated with each.

Type: Array of ResourceTagMapping (p. 41) objects

Errors
For information about the errors that are common to all actions, see Common Errors (p. 48).

InternalServiceException

The request processing failed because of an unknown error, exception, or failure. You can retry the
request.

HTTP Status Code: 500

InvalidParameterException

This error indicates one of the following:

• A parameter is missing.
• A malformed string was supplied for the request parameter.
• An out-of-range value was supplied for the request parameter.
• The target ID is invalid, unsupported, or doesn't exist.
• You can't access the Amazon S3 bucket for report storage. For more information, see Additional
Requirements for Organization-wide Tag Compliance Reports in the AWS Organizations User
Guide.

HTTP Status Code: 400

PaginationTokenExpiredException

A PaginationToken is valid for a maximum of 15 minutes. Your request was denied because the
specified PaginationToken has expired.

API Version 2017-01-26

16
 Resource Groups Tagging API API Reference
Example

HTTP Status Code: 400

ThrottledException

The request was denied to limit the frequency of submitted requests.

HTTP Status Code: 400

Example
Sample Request

POST / HTTP/1.1
Host: tagging.us-west-2.amazonaws.com
Accept-Encoding: identity
Content-Length: 80
X-Amz-Target: ResourceGroupsTaggingAPI_20170126.GetResources
X-Amz-Date: 20191201T214524Z
User-Agent: aws-cli/1.11.79 Python/2.7.9 Windows/7 botocore/1.5.42
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS
{
"ExcludeCompliantResources": null,
"IncludeComplianceDetails": true,
"PaginationToken":" 1
}

Sample Response

HTTP/1.1 200 OK
x-amzn-RequestId: 14bc735b-26da-11e7-a933-67e2d2f3ef37
Content-Type: application/x-amz-json-1.1
Content-Length: 4060
Date: Sun, 1 Dec 2019 21:45:25 GMT
{
"PaginationToken": "",
"ResourceTagMappingList": [
{
"ComplianceDetails":
{"ComplianceStatus":true,"KeysWithNoncompliantValues":[],"NoncompliantKeys":[]},
"ResourceARN": "arn:aws:inspector:us-
west-2:123456789012:target/0-nvgVhaxX/template/0-7sbz2Kz0",
"Tags": []
}
]
}

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

API Version 2017-01-26

17
 Resource Groups Tagging API API Reference
See Also

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2017-01-26

18
 Resource Groups Tagging API API Reference
GetTagKeys

GetTagKeys
Returns all tag keys in the specified Region for the AWS account.

Request Syntax
{
"PaginationToken": "string"
}

Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 46).

The request accepts the following data in JSON format.

PaginationToken (p. 19)

A string that indicates that additional data is available. Leave this value empty for your initial
request. If the response includes a PaginationToken, use that string for this value to request an
additional page of data.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 2048.

Pattern: [\s\S]*

Required: No

Response Syntax
{
"PaginationToken": "string",
"TagKeys": [ "string" ]
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

PaginationToken (p. 19)

A string that indicates that the response contains more data than can be returned in a single
response. To receive additional data, specify this string for the PaginationToken value in a
subsequent request.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 2048.

API Version 2017-01-26

19
 Resource Groups Tagging API API Reference
Errors

Pattern: [\s\S]*
TagKeys (p. 19)

A list of all tag keys in the AWS account.

Type: Array of strings

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [\s\S]*

Errors
For information about the errors that are common to all actions, see Common Errors (p. 48).

InternalServiceException

The request processing failed because of an unknown error, exception, or failure. You can retry the
request.

HTTP Status Code: 500

InvalidParameterException

This error indicates one of the following:

• A parameter is missing.
• A malformed string was supplied for the request parameter.
• An out-of-range value was supplied for the request parameter.
• The target ID is invalid, unsupported, or doesn't exist.
• You can't access the Amazon S3 bucket for report storage. For more information, see Additional
Requirements for Organization-wide Tag Compliance Reports in the AWS Organizations User
Guide.

HTTP Status Code: 400

PaginationTokenExpiredException

A PaginationToken is valid for a maximum of 15 minutes. Your request was denied because the
specified PaginationToken has expired.

HTTP Status Code: 400

ThrottledException

The request was denied to limit the frequency of submitted requests.

HTTP Status Code: 400

Example
Sample Request

POST / HTTP/1.1
Host: tagging.us-west-2.amazonaws.com

API Version 2017-01-26

20
 Resource Groups Tagging API API Reference
See Also

Accept-Encoding: identity
Content-Length: 2
X-Amz-Target: ResourceGroupsTaggingAPI_20170126.GetTagKeys
X-Amz-Date: 20170421T214126Z
User-Agent: aws-cli/1.11.79 Python/2.7.9 Windows/7 botocore/1.5.42
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS
{}

Sample Response

HTTP/1.1 200 OK
x-amzn-RequestId: 462f0799-26db-11e7-a88c-a74e0c5622c9
Content-Type: application/x-amz-json-1.1
Content-Length: 79
Date: Fri, 21 Apr 2017 21:41:27 GMT
{
"PaginationToken": "",
"TagKeys": [
"Example",
"Example1",
"Example2"
]
}

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

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2017-01-26

21
 Resource Groups Tagging API API Reference
GetTagValues

GetTagValues
Returns all tag values for the specified key in the specified Region for the AWS account.

Request Syntax
{
"Key": "string",
"PaginationToken": "string"
}

Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 46).

The request accepts the following data in JSON format.

Key (p. 22)

The key for which you want to list all existing values in the specified Region for the AWS account.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [\s\S]*

Required: Yes
PaginationToken (p. 22)

A string that indicates that additional data is available. Leave this value empty for your initial
request. If the response includes a PaginationToken, use that string for this value to request an
additional page of data.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 2048.

Pattern: [\s\S]*

Required: No

Response Syntax
{
"PaginationToken": "string",
"TagValues": [ "string" ]
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

API Version 2017-01-26

22
 Resource Groups Tagging API API Reference
Errors

The following data is returned in JSON format by the service.

PaginationToken (p. 22)

A string that indicates that the response contains more data than can be returned in a single
response. To receive additional data, specify this string for the PaginationToken value in a
subsequent request.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 2048.

Pattern: [\s\S]*
TagValues (p. 22)

A list of all tag values for the specified key in the AWS account.

Type: Array of strings

Length Constraints: Minimum length of 0. Maximum length of 256.

Pattern: [\s\S]*

Errors
For information about the errors that are common to all actions, see Common Errors (p. 48).

InternalServiceException

The request processing failed because of an unknown error, exception, or failure. You can retry the
request.

HTTP Status Code: 500

InvalidParameterException

This error indicates one of the following:

• A parameter is missing.
• A malformed string was supplied for the request parameter.
• An out-of-range value was supplied for the request parameter.
• The target ID is invalid, unsupported, or doesn't exist.
• You can't access the Amazon S3 bucket for report storage. For more information, see Additional
Requirements for Organization-wide Tag Compliance Reports in the AWS Organizations User
Guide.

HTTP Status Code: 400

PaginationTokenExpiredException

A PaginationToken is valid for a maximum of 15 minutes. Your request was denied because the
specified PaginationToken has expired.

HTTP Status Code: 400

ThrottledException

The request was denied to limit the frequency of submitted requests.

HTTP Status Code: 400

API Version 2017-01-26

23
 Resource Groups Tagging API API Reference
Example

Example
Sample Request

POST / HTTP/1.1
Host: tagging.us-west-2.amazonaws.com
Accept-Encoding: identity
Content-Length: 18
X-Amz-Target: ResourceGroupsTaggingAPI_20170126.GetTagValues
X-Amz-Date: 20170421T214524Z
User-Agent: aws-cli/1.11.79 Python/2.7.9 Windows/7 botocore/1.5.42
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS
{
"Key": "Example_key"
}

Sample Response

HTTP/1.1 200 OK
x-amzn-RequestId: d3cf21f0-26db-11e7-a532-75e05382c8b1
Content-Type: application/x-amz-json-1.1
Content-Length: 42
Date: Fri, 21 Apr 2017 21:45:25 GMT
{
"PaginationToken": "",
"TagValues": [
"Example_value"
]
}

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

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2017-01-26

24
 Resource Groups Tagging API API Reference
StartReportCreation

StartReportCreation
Generates a report that lists all tagged resources in accounts across your organization and tells whether
each resource is compliant with the effective tag policy. Compliance data is refreshed daily.

The generated report is saved to the following location:

s3://example-bucket/AwsTagPolicies/o-exampleorgid/YYYY-MM-ddTHH:mm:ssZ/
report.csv

You can call this operation only from the organization's master account and from the us-east-1 Region.

Request Syntax
{
"S3Bucket": "string"
}

Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 46).

The request accepts the following data in JSON format.

S3Bucket (p. 25)

The name of the Amazon S3 bucket where the report will be stored; for example:

awsexamplebucket

For more information on S3 bucket requirements, including an example bucket policy, see the
example S3 bucket policy on this page.

Type: String

Length Constraints: Minimum length of 3. Maximum length of 63.

Pattern: [\s\S]*

Required: Yes

Response Elements
If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors
For information about the errors that are common to all actions, see Common Errors (p. 48).

ConcurrentModificationException

The target of the operation is currently being modified by a different request. Try again later.

HTTP Status Code: 400

API Version 2017-01-26

25
 Resource Groups Tagging API API Reference
Examples

ConstraintViolationException

The request was denied because performing this operation violates a constraint.

Some of the reasons in the following list might not apply to this specific operation.
• You must meet the prerequisites for using tag policies. For information, see Prerequisites and
Permissions for Using Tag Policies in the AWS Organizations User Guide.
• You must enable the tag policies service principal (tagpolicies.tag.amazonaws.com) to
integrate with AWS Organizations For information, see EnableAWSServiceAccess.
• You must have a tag policy attached to the organization root, an OU, or an account.

HTTP Status Code: 400

InternalServiceException

The request processing failed because of an unknown error, exception, or failure. You can retry the
request.

HTTP Status Code: 500

InvalidParameterException

This error indicates one of the following:

• A parameter is missing.
• A malformed string was supplied for the request parameter.
• An out-of-range value was supplied for the request parameter.
• The target ID is invalid, unsupported, or doesn't exist.
• You can't access the Amazon S3 bucket for report storage. For more information, see Additional
Requirements for Organization-wide Tag Compliance Reports in the AWS Organizations User
Guide.

HTTP Status Code: 400

ThrottledException

The request was denied to limit the frequency of submitted requests.

HTTP Status Code: 400

Examples
Sample S3 policy
Before creating the report, you must grant access for the tag policies service principal to an Amazon
S3 bucket for report storage. Attach the following bucket policy to the bucket. If you don't know your
organization ID, you can call DescribeOrganization to find it.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "TagPolicyACL",
"Effect": "Allow",
"Principal": {
"Service": [
"tagpolicies.tag.amazonaws.com"
]
},

API Version 2017-01-26

26
 Resource Groups Tagging API API Reference
See Also

"Action": "s3:GetBucketAcl",
"Resource": "arn:aws:s3:::your-bucket-name"
},
{
"Sid": "TagPolicyBucketDelivery",
"Effect": "Allow",
"Principal": {
"Service": [
"tagpolicies.tag.amazonaws.com"
]
},
"Action": [
"s3:PutObject",
"s3:PutObjectAcl"
],
"Resource": "arn:aws:s3:::your-bucket-name/AwsTagPolicies/your-org-id/*"
}
]
}

Example
Sample Request

POST / HTTP/1.1
Host: tagging.us-east-1.amazonaws.com
Accept-Encoding: identity
Content-Length: 20
X-Amz-Target: ResourceGroupsTaggingAPI_20170126.StartReportCreation
X-Amz-Date: 20191201T214524Z
User-Agent: aws-cli/1.11.79 Python/2.7.9 Windows/7 botocore/1.5.42
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS
{
"S3Bucket": "awsexamplebucket"
}

Example
Sample Response

HTTP/1.1 200 OK
x-amzn-RequestID: d3cf21f0-26db-11e7-a532-75e05382c8b1
Content-Type: application/x-amz-json-1.1
Date: Sun, 1 Dec 2019 21:45:25 GMT
{}

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

• AWS Command Line Interface

API Version 2017-01-26

27
 Resource Groups Tagging API API Reference
See Also

• AWS SDK for .NET

• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2017-01-26

28
 Resource Groups Tagging API API Reference
TagResources

TagResources
Applies one or more tags to the specified resources. Note the following:

• Not all resources can have tags. For a list of services that support tagging, see this list.
• Each resource can have up to 50 tags. For other limits, see Tag Naming and Usage Conventions in the
AWS General Reference.
• You can only tag resources that are located in the specified Region for the AWS account.
• To add tags to a resource, you need the necessary permissions for the service that the resource belongs
to as well as permissions for adding tags. For more information, see this list.

Request Syntax
{
"ResourceARNList": [ "string" ],
"Tags": {
"string" : "string"
}
}

Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 46).

The request accepts the following data in JSON format.

ResourceARNList (p. 29)

A list of ARNs. An ARN (Amazon Resource Name) uniquely identifies a resource. You can specify a
minimum of 1 and a maximum of 20 ARNs (resources) to tag. An ARN can be set to a maximum
of 1600 characters. For more information, see Amazon Resource Names (ARNs) and AWS Service
Namespaces in the AWS General Reference.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 20 items.

Length Constraints: Minimum length of 1. Maximum length of 1011.

Pattern: [\s\S]*

Required: Yes
Tags (p. 29)

The tags that you want to add to the specified resources. A tag consists of a key and a value that you
define.

Type: String to string map

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Key Pattern: [\s\S]*

Value Length Constraints: Minimum length of 0. Maximum length of 256.

API Version 2017-01-26

29
 Resource Groups Tagging API API Reference
Response Syntax

Value Pattern: [\s\S]*

Required: Yes

Response Syntax
{
"FailedResourcesMap": {
"string" : {
"ErrorCode": "string",
"ErrorMessage": "string",
"StatusCode": number
}
}
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

FailedResourcesMap (p. 30)

A map containing a key-value pair for each failed item that couldn't be tagged. The key is the ARN
of the failed resource. The value is a FailureInfo object that contains an error code, a status code,
and an error message. If there are no errors, the FailedResourcesMap is empty.

Type: String to FailureInfo (p. 39) object map

Key Length Constraints: Minimum length of 1. Maximum length of 1011.

Key Pattern: [\s\S]*

Errors
For information about the errors that are common to all actions, see Common Errors (p. 48).

InternalServiceException

The request processing failed because of an unknown error, exception, or failure. You can retry the
request.

HTTP Status Code: 500

InvalidParameterException

This error indicates one of the following:

• A parameter is missing.
• A malformed string was supplied for the request parameter.
• An out-of-range value was supplied for the request parameter.
• The target ID is invalid, unsupported, or doesn't exist.
• You can't access the Amazon S3 bucket for report storage. For more information, see Additional
Requirements for Organization-wide Tag Compliance Reports in the AWS Organizations User
Guide.

API Version 2017-01-26

30
 Resource Groups Tagging API API Reference
Example

HTTP Status Code: 400

ThrottledException

The request was denied to limit the frequency of submitted requests.

HTTP Status Code: 400

Example
Sample Request

POST / HTTP/1.1
Host: tagging.us-west-2.amazonaws.com
Accept-Encoding: identity
Content-Length: 82
X-Amz-Target: ResourceGroupsTaggingAPI_20170126.TagResources
X-Amz-Date: 20170421T214834Z
User-Agent: aws-cli/1.11.79 Python/2.7.9 Windows/7 botocore/1.5.42
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS
{
"ResourceARNList": [
"arn:aws:s3:::example_bucket"
],
"Tags": {
"key": "Example_key"
}
}

Sample Response

HTTP/1.1 200 OK
x-amzn-RequestId: 45352206-26dc-11e7-8812-6fb02084e31d
Content-Type: application/x-amz-json-1.1
Content-Length: 0
Date: Fri, 21 Apr 2017 21:48:35 GMT

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

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript

API Version 2017-01-26

31
 Resource Groups Tagging API API Reference
See Also

• AWS SDK for PHP V3

• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2017-01-26

32
 Resource Groups Tagging API API Reference
UntagResources

UntagResources
Removes the specified tags from the specified resources. When you specify a tag key, the action removes
both that key and its associated value. The operation succeeds even if you attempt to remove tags from
a resource that were already removed. Note the following:

• To remove tags from a resource, you need the necessary permissions for the service that the resource
belongs to as well as permissions for removing tags. For more information, see this list.
• You can only tag resources that are located in the specified Region for the AWS account.

Request Syntax
{
"ResourceARNList": [ "string" ],
"TagKeys": [ "string" ]
}

Request Parameters
For information about the parameters that are common to all actions, see Common
Parameters (p. 46).

The request accepts the following data in JSON format.

ResourceARNList (p. 33)

A list of ARNs. An ARN (Amazon Resource Name) uniquely identifies a resource. You can specify a
minimum of 1 and a maximum of 20 ARNs (resources) to untag. An ARN can be set to a maximum
of 1600 characters. For more information, see Amazon Resource Names (ARNs) and AWS Service
Namespaces in the AWS General Reference.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 20 items.

Length Constraints: Minimum length of 1. Maximum length of 1011.

Pattern: [\s\S]*

Required: Yes
TagKeys (p. 33)

A list of the tag keys that you want to remove from the specified resources.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 50 items.

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [\s\S]*

Required: Yes

API Version 2017-01-26

33
 Resource Groups Tagging API API Reference
Response Syntax

Response Syntax
{
"FailedResourcesMap": {
"string" : {
"ErrorCode": "string",
"ErrorMessage": "string",
"StatusCode": number
}
}
}

Response Elements
If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

FailedResourcesMap (p. 34)

Details of resources that could not be untagged. An error code, status code, and error message are
returned for each failed item.

Type: String to FailureInfo (p. 39) object map

Key Length Constraints: Minimum length of 1. Maximum length of 1011.

Key Pattern: [\s\S]*

Errors
For information about the errors that are common to all actions, see Common Errors (p. 48).

InternalServiceException

The request processing failed because of an unknown error, exception, or failure. You can retry the
request.

HTTP Status Code: 500

InvalidParameterException

This error indicates one of the following:

• A parameter is missing.
• A malformed string was supplied for the request parameter.
• An out-of-range value was supplied for the request parameter.
• The target ID is invalid, unsupported, or doesn't exist.
• You can't access the Amazon S3 bucket for report storage. For more information, see Additional
Requirements for Organization-wide Tag Compliance Reports in the AWS Organizations User
Guide.

HTTP Status Code: 400

ThrottledException

The request was denied to limit the frequency of submitted requests.

API Version 2017-01-26

34
 Resource Groups Tagging API API Reference
Example

HTTP Status Code: 400

Example
Sample Request

POST / HTTP/1.1
Host: tagging.us-west-2.amazonaws.com
Accept-Encoding: identity
Content-Length: 74
X-Amz-Target: ResourceGroupsTaggingAPI_20170126.UntagResources
X-Amz-Date: 20170421T215122Z
User-Agent: aws-cli/1.11.79 Python/2.7.9 Windows/7 botocore/1.5.42
Content-Type: application/x-amz-json-1.1
Authorization: AUTHPARAMS
{
"TagKeys": [
"key"
],
"ResourceARNList": [
"arn:aws:s3:::examplebucket"
]
}

Sample Response

HTTP/1.1 200 OK
x-amzn-RequestId: a923ddd9-26dc-11e7-bf86-49f2fe9ee8df
Content-Type: application/x-amz-json-1.1
Content-Length: 25
Date: Fri, 21 Apr 2017 21:51:23 GMT
{
"FailedResourcesMap": {}
}

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

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python

API Version 2017-01-26

35
 Resource Groups Tagging API API Reference
See Also

• AWS SDK for Ruby V2

API Version 2017-01-26

36
 Resource Groups Tagging API API Reference

Data Types
The AWS Resource Groups Tagging API API contains several data types that various actions use. This
section describes each data type in detail.
Note
The order of each element in a data type structure is not guaranteed. Applications should not
assume a particular order.

The following data types are supported:

• ComplianceDetails (p. 38)

• FailureInfo (p. 39)
• ResourceTagMapping (p. 41)
• Summary (p. 42)
• Tag (p. 44)
• TagFilter (p. 45)

API Version 2017-01-26

37
 Resource Groups Tagging API API Reference
ComplianceDetails

ComplianceDetails
Information that shows whether a resource is compliant with the effective tag policy, including details on
any noncompliant tag keys.

Contents
ComplianceStatus

Whether a resource is compliant with the effective tag policy.

Type: Boolean

Required: No
KeysWithNoncompliantValues

These are keys defined in the effective policy that are on the resource with either incorrect case
treatment or noncompliant values.

Type: Array of strings

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [\s\S]*

Required: No
NoncompliantKeys

These tag keys on the resource are noncompliant with the effective tag policy.

Type: Array of strings

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [\s\S]*

Required: No

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

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2017-01-26

38
 Resource Groups Tagging API API Reference
FailureInfo

FailureInfo
Information about the errors that are returned for each failed resource. This information can include
InternalServiceException and InvalidParameterException errors. It can also include any valid
error code returned by the AWS service that hosts the resource that the ARN key represents.

The following are common error codes that you might receive from other AWS services:

• InternalServiceException – This can mean that the Resource Groups Tagging API didn't receive a
response from another AWS service. It can also mean the the resource type in the request is not
supported by the Resource Groups Tagging API. In these cases, it's safe to retry the request and then
call GetResources to verify the changes.
• AccessDeniedException – This can mean that you need permission to calling tagging operations in the
AWS service that contains the resource. For example, to use the Resource Groups Tagging API to tag a
CloudWatch alarm resource, you need permission to call TagResources and TagResource in the
CloudWatch API.

For more information on errors that are generated from other AWS services, see the documentation for
that service.

Contents
ErrorCode

The code of the common error. Valid values include InternalServiceException,

InvalidParameterException, and any valid error code returned by the AWS service that hosts
the resource that you want to tag.

Type: String

Valid Values: InternalServiceException | InvalidParameterException

Required: No
ErrorMessage

The message of the common error.

Type: String

Required: No
StatusCode

The HTTP status code of the common error.

Type: Integer

Required: No

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

• AWS SDK for C++

• AWS SDK for Go

API Version 2017-01-26

39
 Resource Groups Tagging API API Reference
See Also

• AWS SDK for Java

• AWS SDK for Ruby V2

API Version 2017-01-26

40
 Resource Groups Tagging API API Reference
ResourceTagMapping

ResourceTagMapping
A list of resource ARNs and the tags (keys and values) that are associated with each.

Contents
ComplianceDetails

Information that shows whether a resource is compliant with the effective tag policy, including
details on any noncompliant tag keys.

Type: ComplianceDetails (p. 38) object

Required: No
ResourceARN

The ARN of the resource.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1011.

Pattern: [\s\S]*

Required: No
Tags

The tags that have been applied to one or more AWS resources.

Type: Array of Tag (p. 44) objects

Required: No

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

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2017-01-26

41
 Resource Groups Tagging API API Reference
Summary

Summary
A count of noncompliant resources.

Contents
LastUpdated

The timestamp that shows when this summary was generated in this Region.

Type: String

Required: No
NonCompliantResources

The count of noncompliant resources.

Type: Long

Required: No
Region

The AWS Region that the summary applies to.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Pattern: [\s\S]*

Required: No
ResourceType

The AWS resource type.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 256.

Pattern: [\s\S]*

Required: No
TargetId

The account identifier or the root identifier of the organization. If you don't know the root ID, you
can call the AWS Organizations ListRoots API.

Type: String

Length Constraints: Minimum length of 6. Maximum length of 68.

Pattern: [\s\S]*

Required: No
TargetIdType

Whether the target is an account, an OU, or the organization root.

Type: String

API Version 2017-01-26

42
 Resource Groups Tagging API API Reference
See Also

Valid Values: ACCOUNT | OU | ROOT

Required: No

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

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2017-01-26

43
 Resource Groups Tagging API API Reference
Tag

Tag
The metadata that you apply to AWS resources to help you categorize and organize them. Each tag
consists of a key and a value, both of which you define. For more information, see Tagging AWS
Resources in the AWS General Reference.

Contents
Key

One part of a key-value pair that makes up a tag. A key is a general label that acts like a category for
more specific tag values.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [\s\S]*

Required: Yes
Value

One part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category
(key). The value can be empty or null.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 256.

Pattern: [\s\S]*

Required: Yes

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

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2017-01-26

44
 Resource Groups Tagging API API Reference
TagFilter

TagFilter
A list of tags (keys and values) that are used to specify the associated resources.

Contents
Key

One part of a key-value pair that makes up a tag. A key is a general label that acts like a category for
more specific tag values.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [\s\S]*

Required: No
Values

One part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category
(key). The value can be empty or null.

Type: Array of strings

Array Members: Minimum number of 0 items. Maximum number of 20 items.

Length Constraints: Minimum length of 0. Maximum length of 256.

Pattern: [\s\S]*

Required: No

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

• AWS SDK for C++

• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for Ruby V2

API Version 2017-01-26

45
 Resource Groups Tagging API API Reference

Common Parameters
The following list contains the parameters that all actions use for signing Signature Version 4 requests
with a query string. Any action-specific parameters are listed in the topic for that action. For more
information about Signature Version 4, see Signature Version 4 Signing Process in the Amazon Web
Services General Reference.

Action

The action to be performed.

Type: string

Required: Yes
Version

The API version that the request is written for, expressed in the format YYYY-MM-DD.

Type: string

Required: Yes
X-Amz-Algorithm

The hash algorithm that you used to create the request signature.

Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.

Type: string

Valid Values: AWS4-HMAC-SHA256

Required: Conditional
X-Amz-Credential

The credential scope value, which is a string that includes your access key, the date, the region you
are targeting, the service you are requesting, and a termination string ("aws4_request"). The value is
expressed in the following format: access_key/YYYYMMDD/region/service/aws4_request.

For more information, see Task 2: Create a String to Sign for Signature Version 4 in the Amazon Web
Services General Reference.

Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.

Type: string

Required: Conditional
X-Amz-Date

The date that is used to create the signature. The format must be ISO 8601 basic format
(YYYYMMDD'T'HHMMSS'Z'). For example, the following date time is a valid X-Amz-Date value:
20120325T120000Z.

Condition: X-Amz-Date is optional for all requests; it can be used to override the date used for
signing requests. If the Date header is specified in the ISO 8601 basic format, X-Amz-Date is

API Version 2017-01-26

46
 Resource Groups Tagging API API Reference

not required. When X-Amz-Date is used, it always overrides the value of the Date header. For
more information, see Handling Dates in Signature Version 4 in the Amazon Web Services General
Reference.

Type: string

Required: Conditional
X-Amz-Security-Token

The temporary security token that was obtained through a call to AWS Security Token Service (AWS
STS). For a list of services that support temporary security credentials from AWS Security Token
Service, go to AWS Services That Work with IAM in the IAM User Guide.

Condition: If you're using temporary security credentials from the AWS Security Token Service, you
must include the security token.

Type: string

Required: Conditional
X-Amz-Signature

Specifies the hex-encoded signature that was calculated from the string to sign and the derived
signing key.

Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.

Type: string

Required: Conditional
X-Amz-SignedHeaders

Specifies all the HTTP headers that were included as part of the canonical request. For more
information about specifying signed headers, see Task 1: Create a Canonical Request For Signature
Version 4 in the Amazon Web Services General Reference.

Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.

Type: string

Required: Conditional

API Version 2017-01-26

47
 Resource Groups Tagging API API Reference

Common Errors
This section lists the errors common to the API actions of all AWS services. For errors specific to an API
action for this service, see the topic for that API action.

AccessDeniedException

You do not have sufficient access to perform this action.

HTTP Status Code: 400

IncompleteSignature

The request signature does not conform to AWS standards.

HTTP Status Code: 400

InternalFailure

The request processing has failed because of an unknown error, exception or failure.

HTTP Status Code: 500

InvalidAction

The action or operation requested is invalid. Verify that the action is typed correctly.

HTTP Status Code: 400

InvalidClientTokenId

The X.509 certificate or AWS access key ID provided does not exist in our records.

HTTP Status Code: 403

InvalidParameterCombination

Parameters that must not be used together were used together.

HTTP Status Code: 400

InvalidParameterValue

An invalid or out-of-range value was supplied for the input parameter.

HTTP Status Code: 400

InvalidQueryParameter

The AWS query string is malformed or does not adhere to AWS standards.

HTTP Status Code: 400

MalformedQueryString

The query string contains a syntax error.

HTTP Status Code: 404

MissingAction

The request is missing an action or a required parameter.

HTTP Status Code: 400

API Version 2017-01-26

48
 Resource Groups Tagging API API Reference

MissingAuthenticationToken

The request must contain either a valid (registered) AWS access key ID or X.509 certificate.

HTTP Status Code: 403

MissingParameter

A required parameter for the specified action is not supplied.

HTTP Status Code: 400

OptInRequired

The AWS access key ID needs a subscription for the service.

HTTP Status Code: 403

RequestExpired

The request reached the service more than 15 minutes after the date stamp on the request or more
than 15 minutes after the request expiration date (such as for pre-signed URLs), or the date stamp
on the request is more than 15 minutes in the future.

HTTP Status Code: 400

ServiceUnavailable

The request has failed due to a temporary failure of the server.

HTTP Status Code: 503

ThrottlingException

The request was denied due to request throttling.

HTTP Status Code: 400

ValidationError

The input fails to satisfy the constraints specified by an AWS service.

HTTP Status Code: 400

API Version 2017-01-26

49