Managing monitored tag keys

Amazon EC2 Capacity Manager lets you select tag keys from your Amazon EC2 resources (for example, environment or team) to use as dimensions when analyzing your capacity data. After a tag key is activated, you can group and filter your metrics by that tag's values — just like you can with Region, Instance Type, or Availability Zone.

Each account can monitor up to five tag keys. Capacity Manager-provided tags do not count toward this limit.

Capacity Manager-provided tags

Capacity Manager includes a set of default tags for every account. These do not count toward your tag key limit. Capacity Manager-provided tags represent commonly used grouping dimensions and include:

• aws:autoscaling:groupName — EC2 Auto Scaling Group

• aws:eks:cluster-name — EKS cluster name

• eks:kubernetes-node-pool-name — EKS Kubernetes node pool

• karpenter.sh/nodepool — Karpenter node pool

Capacity Manager-provided tags appear in GetCapacityManagerMonitoredTagKeys with CapacityManagerProvided set to true and cannot be activated or deactivated by the customer. When Capacity Manager is first enabled, Capacity Manager-provided tags start in activating status and transition to activated after Capacity Manager receives the first data point that includes a Capacity Manager-provided tag, typically within one to two hours.

Tag lifecycle

Monitored tag keys progress through the following statuses:

Status	Description
activating	The tag key is registered. Capacity Manager is preparing to collect data for this tag. You cannot query metrics using a tag in this status.
activated	Tag data is being ingested and is queryable through the metric APIs and in data exports.
suspended	The tag key has exceeded the threshold of 100,000 unique tag values. The tag still counts toward your limit, but Capacity Manager no longer ingests data for it. If your tag value usage decreases below the threshold for a sustained period, the tag is reactivated automatically.
deactivating	The tag key is being removed. It will no longer appear in GetCapacityManagerMonitoredTagKeys after deactivation completes.

When a tag is in suspended status, GetCapacityManagerMonitoredTagKeys returns the following status message: "Tag suspended due to too many tag values. Reduce the usage of the tag or deactivate it."

Note

If you deactivate a tag key and later re-activate the same key, only data ingested after re-activation is queryable. Historical data from the previous activation is not accessible. The EarliestDatapointTimestamp resets with each new activation.

Activate and deactivate monitored tag keys

You can activate tag keys to begin monitoring them as dimensions, or deactivate tag keys you no longer need. Activation is asynchronous — the tag enters an activating state and transitions to activated after Capacity Manager begins receiving data for that tag. Deactivation removes the tag key from your monitored set.

Note

When activating a tag key, enter only the key name (for example, environment). Capacity Manager automatically makes it available as a dimension for grouping and filtering your metrics.

Console

To activate or deactivate monitored tag keys

1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

2. In the navigation pane, choose Capacity Manager.

3. Choose the Settings tab.

4. In the Monitored tag keys section, choose Manage tag keys.

5. To activate a tag key, enter the tag key name and choose Add. To deactivate a tag key, select the tag key and choose Remove.

6. Choose Save changes.

AWS CLI

To activate tag keys

Use the following command to activate one or more tag keys:

aws ec2 update-capacity-manager-monitored-tag-keys \
    --activate-tag-keys "environment" "teamId"
                

The output shows the tag keys and their initial statuses:

{
    "CapacityManagerTagKeys": [
        {
            "TagKey": "environment",
            "Status": "activating"
        },
        {
            "TagKey": "teamId",
            "Status": "activating"
        }
    ]
}

To deactivate tag keys

Use the following command to deactivate one or more tag keys:

aws ec2 update-capacity-manager-monitored-tag-keys \
    --deactivate-tag-keys "project"
                

The output shows the updated statuses:

{
    "CapacityManagerTagKeys": [
        {
            "TagKey": "project",
            "Status": "deactivating"
        }
    ]
}

You can activate and deactivate tag keys in the same request:

aws ec2 update-capacity-manager-monitored-tag-keys \
    --activate-tag-keys "environment" "teamId" \
    --deactivate-tag-keys "project"
                

View monitored tag keys

You can view all monitored tag keys for your account, including their current status and the earliest timestamp from which data is available.

Console

To view monitored tag keys

1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

2. In the navigation pane, choose Capacity Manager.

3. Choose the Settings tab.

4. In the Monitored tag keys section, view your tag keys, their statuses, and whether they are Capacity Manager-provided tags.

AWS CLI

To view monitored tag keys

Run the following command:

aws ec2 get-capacity-manager-monitored-tag-keys
                

The output lists all tag keys, including Capacity Manager-provided tags and customer-managed tags:

{
    "CapacityManagerTagKeys": [
        {
            "TagKey": "aws:autoscaling:groupName",
            "Status": "activated",
            "CapacityManagerProvided": true,
            "earliestDatapointTimestamp": "2026-04-08T00:00:00"
        },
        {
            "TagKey": "environment",
            "Status": "activated",
            "CapacityManagerProvided": false,
            "earliestDatapointTimestamp": "2025-08-11T22:00:00"
        }
    ]
}

The CapacityManagerProvided field indicates whether a tag is a Capacity Manager-provided tag (true) or a customer-managed tag (false). Capacity Manager-provided tags do not count toward your tag key limit. The EarliestDatapointTimestamp indicates the earliest point in time from which data is available for that tag key.

Query metrics using tag dimensions

After a tag key reaches activated status, you can use it as a dimension in GetCapacityManagerMetricDimensions and GetCapacityManagerMetricData.

To query metrics grouped by a tag dimension

Use the following command:

aws ec2 get-capacity-manager-metric-dimensions \
    --group-by tag:environment account-id \
    --filter-by 'DimensionCondition={Dimension=tag:environment,Comparison=equals,Values=[prod]}'
          

When you group by a tag dimension, the results include all resources in your account — not only those that have the tag. Resources that do not have a value for the tag are grouped into a separate bucket with an empty string value. For example, if your account used 800 vCPU hours in a given period and only some of those resources have an environment tag, grouping by the environment tag key might return:

• prod — 300 vCPU hours

• staging — 200 vCPU hours

• "" (empty string) — 300 vCPU hours from resources without an environment tag

This ensures that the totals across all buckets account for your full usage. You can explicitly filter for untagged resources by passing an empty string as the filter value:

--filter-by 'DimensionCondition={Dimension=tag:environment,Comparison=equals,Values=[""]}'
          

Note

If you query with a tag key that is still in activating status, the query is rejected with a 400 error. Wait for the tag's status to change to activated before querying. You can check the status using GetCapacityManagerMonitoredTagKeys.

Note

Queries with a start time before the EarliestDatapointTimestamp of any supplied tag dimension are rejected. Use GetCapacityManagerMonitoredTagKeys to check when data became available for each tag.

Tags in data exports

When you enable tag monitoring, your data exports include activated tag keys and Capacity Manager-provided tags as additional columns. Tag columns appear after all standard columns with headers such as tag:environment and tag:team. Tag columns are sorted alphabetically.

Exports include only tags in activated status. Capacity Manager excludes tags in activating, deactivating, or suspended status.

Note

If you activate a new tag key, existing data exports do not automatically include the new tag. You must create a new data export to include the newly activated tag key as a column.

Organizations and delegated administrator

When your account is part of an AWS Organization with an organization-level Capacity Manager enabled, each account (the organization administrator and the delegated administrator) can independently activate, deactivate, and query tag keys. Each account maintains its own tag status, EarliestDatapointTimestamp, and tag key limit.

An account can only query metric data for tag keys that the account itself has activated. If both the organization administrator and a delegated administrator activate the same tag key (for example, environment), each account tracks its own activation status and data availability independently.

When the delegated administrator deactivates a tag key, the delegated administrator can no longer query data for that tag, even if the organization administrator still has the same tag key activated.

Considerations

• Tag value updates: Tag values for new resources and tags newly applied to existing resources are available within a few hours. If you change the value of an existing tag on a resource, the updated value can take up to 24 hours to reflect in Capacity Manager.

• Activation time: After you activate a tag key, it can take up to 24 hours before the tag transitions to activated status and data becomes queryable. The EarliestDatapointTimestamp represents when data is available, not when the tag was activated.

• Tag key limit: Each account can monitor up to five tag keys. Capacity Manager-provided tags do not count toward this limit.

• Tag key character requirements: Tag keys can contain Unicode letters, digits, white space, and the following characters: _ . : / = + @ -. Tag keys must not exceed 128 characters.

• Re-activation: If you deactivate and re-activate the same tag key, only new data is available. The EarliestDatapointTimestamp resets with each activation.

• Suspended tags: Each tag key supports up to 100,000 unique tag values. If a tag key exceeds this threshold, it is moved to suspended status. The tag still counts toward your limit but data is no longer ingested. Reduce the number of unique values for the tag or deactivate it to free up space for another tag key.