> 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/tags-overview.md).

# Get Started with Tags

ThousandEyes uses tags to help you organize, filter, and manage your platform assets. A tag is a key-value pair, such as `Environment: Production` or `Location: EMEA`. Tags replace the legacy labels system and work across tests, agents, dashboards, and alerts.

By using tags, you can:

* **Improve resource organization:** Group related assets with the same key or value.
* **Streamline integrations:** Standardize metadata to correlate ThousandEyes data with third-party IT service management (ITSM) and application performance monitoring (APM) tools such as ServiceNow and AppDynamics.
* **Enhance analytics:** Use tags to filter dashboard widgets, group data, and create targeted alert rules.

## The Tags Workspace

To open the Tags workspace, select **Manage > Tags**. From this screen, you can view, create, edit, duplicate, delete, and manage assigned items for tags across all product areas (such as Cloud & Enterprise Agents, Endpoint Agents, and Internet Insights).

The Tags list displays:

![Manage > Tags workspace - Tags table with columns for Icon, Tag Key, Tag Value, Tag Type, Product Area, Description, and Date Modified](/files/OgPNlny2821aLhM3ORf5)

* **Icon:** The visual shape and color assigned to the tag.
* **Tag Key:** Editable category text for the tag (for example, `APP` or `DataCenter`).
* **Tag Value:** Editable detail text for the key (for example, `Webex` or `AWS`).
* **Tag Type:** **Static** for tags you assign manually, or **Dynamic** for rule-based tags on Endpoint Experience Agents (the list may show a short summary of the rule).
* **Product Area:** The area of ThousandEyes where the tag applies (for example, Network & App Synthetics tests, Endpoint Experience Agents, or Dashboards).
* **Description:** Optional context about how the tag should be used.
* **Date Modified:** When the tag was last changed (you can sort by this column).

A tag does not have a separate name field. Its visible text comes from its key and optional value. For example, a tag with the key `ISP` and value `Lumen` can appear as `ISP: Lumen`. Some filter pickers show this combined text when you select **Tag**.

Each tag also has a Tag ID, which is a system-created unique ID (UUID format, included in Tags API responses) for one exact key-value pair. The Tag ID stays the same when you rename the tag key or value. The tag key and tag value are text, so they can change.

Renaming a tag is different from deleting and recreating it. A renamed tag keeps the same Tag ID. A deleted tag that you recreate with the same key and value gets a new Tag ID.

This difference matters for filters. Filters that use the Tag ID can keep matching the same tag after a rename. Filters that use key or value text might need updates after someone renames that text.

## Built-In versus Custom Tags

ThousandEyes provides several built-in tags out of the box (such as `Cloud`, `Enterprise`, `IPv4 Compatible`, and `Mobile`). These cannot be deleted. All previously built-in labels have been converted to built-in tags. You can also create custom tags tailored to your organization's specific routing, application, or billing needs.

For step-by-step instructions on creating, assigning, and filtering tags, see [Work with Key-Value Tags](https://docs.thousandeyes.com/product-documentation/tags/working-with-tags).

## Known Limitations and API Behavior

### Fetching Tags via the API

The test details API does not return tag assignments. To retrieve tags for a specific test or agent, use the `GET /v7/tags` endpoint with the `expand=assignments` parameter. Filter the results on the client side by `assignment.type` (for example, `test` or `agent`) and the matching ID.

### Dynamic Tags API Endpoint

In the ThousandEyes platform, Endpoint Agent rule-based tags are called **Dynamic Tags**, but the API endpoint remains `GET /v7/endpoint-labels` for backward compatibility. You can manage Dynamic Tags using either the V7 tags API or the V7 endpoint labels API; both endpoints are synchronized.

### User-Defined Templates

Existing user-created test templates may still show `label` in the JSON editor. This display behavior does not affect functionality: templates continue to work, tests deployed from those templates apply tags correctly, and tags appear in the Tags workspace. New user-defined templates and all certified templates fully support tags.