> For the complete documentation index, see [llms.txt](https://docs.thousandeyes.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thousandeyes.com/product-documentation/tags/working-with-tags.md).

# Work with Key-Value Tags

## Create a New Tag

You can create tags centrally from the Tags workspace or inline while configuring an asset.

To create a tag from the Tags workspace:

1. Navigate to **Manage > Tags**.
2. Select **Add tag**.
3. In the **Key** field, enter editable category text for the tag (up to 64 alphanumeric characters, hyphens, or underscores).

   If you plan to use this tag in an OpenTelemetry streaming integration, avoid spaces and other non-compliant characters in the tag key. Non-compliant keys are excluded from streamed data. For details, see [Tags as Attributes](https://docs.thousandeyes.com/product-documentation/integration-guides/opentelemetry/data-model/data-model-v2/metrics#tags-as-attributes).
4. In the **Value** field, enter the specific value (optional, up to 64 characters).
5. Under **Select shape**, select an icon to represent the tag (such as a circle, triangle, or server icon).
6. Under **Select color**, select a color for the tag.
7. (Optional) Enter a **Description** to help other users understand the tag's purpose.
8. Under **Select tag type**, select **Static tag** or **Dynamic tag**. Dynamic tags apply only to Endpoint Experience Agents and use rules to assign tags automatically; see [Manage dynamic tags for Endpoint Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents/configuring/dynamic-tags).
9. Under **Assign product area to tag**, select the product area for the tag (for example, Network & App Synthetics tests or agents, Endpoint Experience tests, Dashboards, or Connected Devices tests).
10. Select **Save and assign items** to create the tag. Follow the prompts to assign items now, or finish the flow if you do not need to assign any yet.

![Add New Tag side panel - Key, Value, shape, color, description, tag type, product area, and Save and assign items](/files/sSBAM2OGJNII7xCa6Za2)

## Create a Tag Inline

When configuring an asset, such as a test or an agent, you can create a tag on the fly:

1. Select the **Add tags** field on the asset configuration page.
2. Start typing your desired tag. Use a colon (`:`) to separate the key and the value (for example, `Europe: Amsterdam`).
3. If the tag does not exist, the dropdown prompts you to **Create New Tag**.
4. Select **Save**. ThousandEyes applies the new tag to the asset and gives it the default icon and color.

## Assign Tags to Assets

To assign an existing tag to an asset:

1. Open the configuration page for the test, agent, or dashboard.
2. Locate the tag selector field.
3. Select the field to open the dropdown menu. You can scroll through the alphabetical list or type to search.
4. Select the tags you want to apply. You can select multiple tags for a single asset.

## Manage Assigned Items from a Tag

You can assign a tag to multiple assets (such as tests or agents), or remove the tag from them directly from the Tags workspace.

1. Navigate to **Manage > Tags**.
2. Select the **...** (options) menu next to the tag you want to modify.
3. Select **Manage Assigned Items**.

![Tag detail panel with overflow menu open showing Manage Assigned Items](/files/uT3wJBpY3i9JRCGLLup8)

4. In the dialog that appears, select or deselect the items you want to associate with the tag.
5. Select **Save**.

## Filter Using Tags

Tags allow for filtering across the ThousandEyes platform, but the options can vary by surface. On test and agent configuration screens, tag selectors assign exact tags to assets. In views, tag selectors filter or group tests by selected tags.

Dashboard tag filters let you choose how ThousandEyes matches tag data. The filter type controls whether ThousandEyes matches tag text or the tag's stable ID. If **Manage > Tags > Add Filter** shows **Tag**, it means the combined key-value text, such as `ISP: Lumen`. A tag does not have a separate name field. For a short definition of Tag ID, see [Get Started with Tags](https://docs.thousandeyes.com/product-documentation/tags/tags-overview).

| Filter type | What it matches                              | Best use                                                                                        | Rename risk                                                                          | Future tags                                      |
| ----------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------ |
| **Key**     | Tag key text.                                | Use this when you want everything under one category, such as all tags with the key `Location`. | If someone renames the key, filters that use the old key text can stop matching.     | Includes tags created later with the same key.   |
| **Value**   | Tag value text.                              | Use this when you want tags with the same value, such as all tags with the value `EMEA`.        | If someone renames the value, filters that use the old value text can stop matching. | Includes tags created later with the same value. |
| **Tag**     | One exact key-value tag, selected by Tag ID. | Use this when the filter must keep matching the same tag after a rename.                        | Keeps matching when the tag key or value is renamed.                                 | Does not include new tags created later.         |

For example, use **Key** when a dashboard should track a whole category and grow on its own. If you filter by the key `Location`, the widget can show `Location: AMER`, `Location: EMEA`, and `Location: APJC` today, and automatically include `Location: LATAM` if someone creates that tag later. The trade-off is that renaming `Location` to `Region` can break the filter.

Use **Tag** when a dashboard should track one exact key-value pair. If you filter by the tag `ISP: Lumen`, the widget keeps matching that same tag even if someone later edits its key or value, because the filter is tied to the tag's stable ID. The trade-off is that the filter does not automatically include new tags.

If you select all current **Tag** matches in a dashboard filter, ThousandEyes selects the Tag IDs that exist now. New tags are not added automatically. To include tags created later, use **Key** or **Value** when that behavior matches your goal.

* **In dashboards:** Use the global filter or widget-level filters to isolate data. For example, filtering by `APP: Salesforce` will update all applicable widgets to show only data related to that tag.
* **In views:** Use the tag selector to filter test results or group tests by selected tags.
* **In alert rules:** Use tag-based selectors with AND/OR logic to target tests and agents by selected tags.

## Edit or Delete Tags

1. Navigate to **Manage > Tags**.
2. To edit, select the **Edit** icon next to the tag. Note that changing a tag's key or value will update it across all assigned assets.
3. To delete, select the checkbox next to one or more tags, and select **Delete**. *Note: Deleting a tag removes it from all associated assets. This action cannot be undone.*

Renaming a tag's key or value keeps the same Tag ID, but filters that use the old **Key** or **Value** text can stop matching. This can make dashboard widgets or saved filters show **No Data**. Filters that use **Tag** keep matching the renamed tag.