AWS Resource Groups Tagging API actions

This page provides a reference for AWS Resource Groups Tagging API actions available in the workflow automation actions catalog. Use these actions to get, add, update, and remove tags on AWS resources across services.

Prerequisites

For prerequisites and credentials setup, see Set up AWS credentials.

Get tags by ARN

The action identifier is aws.resourceGroupsTaggingApi.getResourceTags.

Returns the tags for one or more AWS resources specified by ARN.

Importante

You cannot combine resourceArnList with tagFilters, resourceTypeFilters, or pagination inputs. AWS rejects that combination with an InvalidParameterException. To find resources by tag or type, use aws.resourceGroupsTaggingApi.getResourcesByTag instead.

The following table describes the input fields for this action.

Input	Type	Description	Example
`awsRoleArn`	String	Optional. IAM role ARN to assume for AWS API calls.	`arn:aws:iam::123456789012:role/my-workflow-role`
`awsAccessKeyId`	String	Optional. AWS access key ID. Pass as a secret.	`${{ :secrets:awsAccessKeyId }}`
`awsSecretAccessKey`	String	Optional. AWS secret access key. Pass as a secret.	`${{ :secrets:awsSecretAccessKey }}`
`awsSessionToken`	String	Optional. Temporary session token for STS authentication. Pass as a secret.	`${{ :secrets:awsSessionToken }}`
`region`	String	Required. AWS region to query.	`us-east-2`
`resourceArnList`	List	Required. List of 1–100 ARNs to retrieve tags for. AWS silently drops nonexistent ARNs.	`["arn:aws:dynamodb:us-east-2:123456789012:table/my-table"]`
`includeComplianceDetails`	Boolean	Optional. Include Tag Policy compliance details in the response.	`false`
`excludeCompliantResources`	Boolean	Optional. Exclude resources compliant with Tag Policies. Only meaningful when `includeComplianceDetails` is `true`.	`false`
`selectors`	List	Optional. JQ selectors to extract specific fields from the action output.	`[{"name": "tags", "expression": ".response.ResourceTagMappingList"}]`

The following table describes the output fields for this action.

Output	Type	Example
`response`	Object	See the get_resources boto3 reference.
`success`	Boolean	`true` or `false`
`errorMessage`	String	`"An error occurred (InvalidParameterException) when calling the GetResources operation: Only one of ResourceARNList or TagFilters can be specified"`

Example workflow

name: get-resource-tags-by-arn
description: 'Get tags for AWS resources by ARN'
steps:
  - name: getResourceTagsByArn
    type: action
    action: aws.resourceGroupsTaggingApi.getResourceTags
    version: '1'
    inputs:
      awsRoleArn: "arn:aws:iam::123456789012:role/my-workflow-role"
      region: "us-east-2"
      resourceArnList:
        - "arn:aws:dynamodb:us-east-2:123456789012:table/my-table"
      selectors:
        - name: tags
          expression: ".response.ResourceTagMappingList"
    next: end

Get resources by tag

The action identifier is aws.resourceGroupsTaggingApi.getResourcesByTag.

Finds AWS resources by tag key/value and/or resource type. Only returns resources that have been tagged.

Importante

You cannot combine tagFilters or resourceTypeFilters with resourceArnList in the same call. AWS rejects that combination with an InvalidParameterException. To retrieve tags for specific ARNs, use aws.resourceGroupsTaggingApi.getResourceTags instead.

The following table describes the input fields for this action.

Input	Type	Description	Example
`awsRoleArn`	String	Optional. IAM role ARN to assume for AWS API calls.	`arn:aws:iam::123456789012:role/my-workflow-role`
`awsAccessKeyId`	String	Optional. AWS access key ID. Pass as a secret.	`${{ :secrets:awsAccessKeyId }}`
`awsSecretAccessKey`	String	Optional. AWS secret access key. Pass as a secret.	`${{ :secrets:awsSecretAccessKey }}`
`awsSessionToken`	String	Optional. Temporary session token for STS authentication. Pass as a secret.	`${{ :secrets:awsSessionToken }}`
`region`	String	Required. AWS region to query.	`us-east-2`
`tagFilters`	List	Optional. Filter by tag key and values. Up to 50 keys, up to 20 values each.	`[{"Key": "product", "Values": ["Workflow"]}]`
`resourceTypeFilters`	List	Optional. Filter by resource type. Up to 100 items.	`["ec2:instance", "s3:bucket"]`
`resourcesPerPage`	Integer	Optional. Maximum number of resources per page (1–100).	`50`
`tagsPerPage`	Integer	Optional. Maximum number of tags per page (100–500). AWS recommends using `resourcesPerPage` instead.	`100`
`paginationToken`	String	Optional. Token from a previous response to retrieve the next page of results. Leave empty on the initial request.	`some-pagination-token`
`includeComplianceDetails`	Boolean	Optional. Include Tag Policy compliance details in the response.	`false`
`excludeCompliantResources`	Boolean	Optional. Exclude resources compliant with Tag Policies. Only meaningful when `includeComplianceDetails` is `true`.	`false`
`selectors`	List	Optional. JQ selectors to extract specific fields from the action output.	`[{"name": "resourceTagMappingList", "expression": ".response.ResourceTagMappingList"}]`

The following table describes the output fields for this action.

Output	Type	Example
`response`	Object	See the get_resources boto3 reference.
`success`	Boolean	`true` or `false`
`errorMessage`	String	`"An error occurred (InvalidParameterException) when calling the GetResources operation: Only one of ResourceARNList or TagFilters can be specified"`

Example workflow

name: find-resources-by-tag
description: 'Find AWS resources by tag'
steps:
  - name: findResourcesByTag
    type: action
    action: aws.resourceGroupsTaggingApi.getResourcesByTag
    version: '1'
    inputs:
      awsRoleArn: "arn:aws:iam::123456789012:role/my-workflow-role"
      region: "us-east-2"
      tagFilters:
        - Key: product
          Values:
            - Workflow
      resourcesPerPage: 50
      selectors:
        - name: resourceTagMappingList
          expression: ".response.ResourceTagMappingList"
    next: end

Add or update tags on resources

The action identifier is aws.resourceGroupsTaggingApi.tagResources.

Adds or updates up to 50 tags on 1–20 AWS resources across services in a single call.

Importante

The action reports partial failures per-ARN in response.FailedResourcesMap rather than as a top-level error. Check response.FailedResourcesMap even when success is true, because one failed ARN in a batch does not fail the entire call.

The following table describes the input fields for this action.

Input	Type	Description	Example
`awsRoleArn`	String	Optional. IAM role ARN to assume for AWS API calls.	`arn:aws:iam::123456789012:role/my-workflow-role`
`awsAccessKeyId`	String	Optional. AWS access key ID. Pass as a secret.	`${{ :secrets:awsAccessKeyId }}`
`awsSecretAccessKey`	String	Optional. AWS secret access key. Pass as a secret.	`${{ :secrets:awsSecretAccessKey }}`
`awsSessionToken`	String	Optional. Temporary session token for STS authentication. Pass as a secret.	`${{ :secrets:awsSessionToken }}`
`region`	String	Required. AWS region of the target resources.	`us-east-2`
`resourceArnList`	List	Required. List of 1–20 ARNs to tag.	`["arn:aws:sqs:us-east-2:123456789012:my-queue"]`
`tags`	Map	Required. Tags to add or update. Up to 50 tags. Each key is 1–128 characters. Each value is 0–256 characters.	`{"Environment": "production", "Team": "platform"}`
`selectors`	List	Optional. JQ selectors to extract specific fields from the action output.	`[{"name": "failedResources", "expression": ".response.FailedResourcesMap"}]`

The following table describes the output fields for this action.

Output	Type	Example
`response`	Object	See the tag_resources boto3 reference. `response.FailedResourcesMap` is empty on full success.
`success`	Boolean	`true` or `false`
`errorMessage`	String	The call populates this when it fails, such as for an auth or permission error. Per-resource failures appear in `response.FailedResourcesMap`.

Example workflow

name: tag-aws-resources
description: 'Add or update tags on AWS resources'
steps:
  - name: tagResources
    type: action
    action: aws.resourceGroupsTaggingApi.tagResources
    version: '1'
    inputs:
      awsRoleArn: "arn:aws:iam::123456789012:role/my-workflow-role"
      region: "us-east-2"
      resourceArnList:
        - "arn:aws:sqs:us-east-2:123456789012:my-queue"
      tags:
        Environment: production
        Team: platform
      selectors:
        - name: failedResources
          expression: ".response.FailedResourcesMap"
    next: end

Remove tags from resources

The action identifier is aws.resourceGroupsTaggingApi.untagResources.

Removes one or more tags from up to 20 AWS resources across services in a single call. Removing a tag key that doesn't exist on a resource succeeds silently.

Importante

The following table describes the input fields for this action.

Input	Type	Description	Example
`awsRoleArn`	String	Optional. IAM role ARN to assume for AWS API calls.	`arn:aws:iam::123456789012:role/my-workflow-role`
`awsAccessKeyId`	String	Optional. AWS access key ID. Pass as a secret.	`${{ :secrets:awsAccessKeyId }}`
`awsSecretAccessKey`	String	Optional. AWS secret access key. Pass as a secret.	`${{ :secrets:awsSecretAccessKey }}`
`awsSessionToken`	String	Optional. Temporary session token for STS authentication. Pass as a secret.	`${{ :secrets:awsSessionToken }}`
`region`	String	Required. AWS region of the target resources.	`us-east-2`
`resourceArnList`	List	Required. List of 1–20 ARNs to remove tags from.	`["arn:aws:sqs:us-east-2:123456789012:my-queue"]`
`tagKeys`	List	Required. Tag keys to remove. 1–50 keys. Removing a key that doesn't exist on a resource succeeds silently.	`["Environment", "Team"]`
`selectors`	List	Optional. JQ selectors to extract specific fields from the action output.	`[{"name": "failedResources", "expression": ".response.FailedResourcesMap"}]`

The following table describes the output fields for this action.

Output	Type	Example
`response`	Object	See the untag_resources boto3 reference. `response.FailedResourcesMap` is empty on full success.
`success`	Boolean	`true` or `false`
`errorMessage`	String	The call populates this when it fails, such as for an auth or permission error. Per-resource failures appear in `response.FailedResourcesMap`.

Example workflow

name: remove-tags-from-resources
description: 'Remove tags from AWS resources'
steps:
  - name: untagResources
    type: action
    action: aws.resourceGroupsTaggingApi.untagResources
    version: '1'
    inputs:
      awsRoleArn: "arn:aws:iam::123456789012:role/my-workflow-role"
      region: "us-east-2"
      resourceArnList:
        - "arn:aws:sqs:us-east-2:123456789012:my-queue"
      tagKeys:
        - Environment
      selectors:
        - name: failedResources
          expression: ".response.FailedResourcesMap"
    next: end

AWS Resource Groups Tagging API actions

Prerequisites.css-21sua1{background:none;border:none;width:0;padding:0;}

Get tags by ARN

Importante

Get resources by tag

Importante

Add or update tags on resources

Importante

Remove tags from resources

Importante

Prerequisites