Set up resource tags

Create and manage resource tags to organize projects, datasets, prompts, and other resources within a LangSmith workspace.

Resource tags are available for Plus and Enterprise plans.

While workspaces help separate trust boundaries and access control, tags help you organize resources within a workspace. Tags are key-value pairs that you can attach to resources.

Not to be confused with commit tags: Resource tags are key-value pairs used to organize and filter workspace resources (projects, datasets, prompts, etc.). Commit tags are labels that reference specific versions in a prompt’s commit history. While both types of tags can use similar terminology (like prod or staging), resource tags help you organize resources across your workspace, while commit tags control which version of a prompt is used in your code.

You can manage resource tags through the LangSmith UI or programmatically via the REST API:

UI

Create a tag

To create resource tags, you must have the workspaces:manage permission (granted to the workspace admin role by default). Editors can apply Application tags to resources they have update access to, but creating tag keys or applying other tag types requires this permission. For more on applying tags to resources, refer to the workspace operations Tags section.

To create a tag:

1. Navigate to the workspace Settings page and click on Resource tags in the left-hand sidebar.

2. Here, you’ll find the existing tag values, grouped by key. LangSmith creates the Application and Environment keys by default. You can use the Application key to filter resources shown in the UI.

3. Select New Tag at the top of the page. You’ll be prompted to enter a key and a value for the tag. Note that you can use an existing key or create a new one.

   

Assign a tag to a resource

Within the same side panel for creating a new tag, you can also assign resources to tags. Search for corresponding resources in the Assign resources section and select the resources you want to tag.

You can only tag workspace-scoped resources with resource tags. This includes Tracing Projects, Annotation Queues, Deployments, Experiments, Datasets, and Prompts.

To un-assign a tag from a resource, click the trash icon next to the tag, both in the tag panel and the resource tag panel.

Delete a tag

You can delete either a key or a value of a tag from the Settings page > Resource tags page. To delete a key, click the trash icon next to the key. To delete a value, click the trash icon next to the value.

If you delete a key, LangSmith will delete all values associated with that key. When you delete a value, you will lose all associations between that value and resources.

API

Manage tags via API

You can create, assign, and query resource tags programmatically using the LangSmith REST API. All tag endpoints live under /api/v1/workspaces/current/ and require an API key.

Set up

Import the requests library and configure your API key and headers. All the following examples assume these variables are in scope:

import os
import requests

LANGSMITH_API_URL = "https://api.smith.langchain.com"
LANGSMITH_API_KEY = os.environ["LANGSMITH_API_KEY"]
headers = {"x-api-key": LANGSMITH_API_KEY, "Content-Type": "application/json"}

Create a tag key

Creating tag keys requires the workspaces:manage permission. If you want to apply the default Application key, skip this step and list existing keys instead.

response = requests.post(
    f"{LANGSMITH_API_URL}/api/v1/workspaces/current/tag-keys",
    headers=headers,
    json={"key": "Environment", "description": "Deployment environment"},
)
response.raise_for_status()
tag_key = response.json()
tag_key_id = tag_key["id"]

Create a tag value

response = requests.post(
    f"{LANGSMITH_API_URL}/api/v1/workspaces/current/tag-keys/{tag_key_id}/tag-values",
    headers=headers,
    json={"value": "production"},
)
response.raise_for_status()
tag_value = response.json()
tag_value_id = tag_value["id"]

Assign a tag to a resource

response = requests.post(
    f"{LANGSMITH_API_URL}/api/v1/workspaces/current/taggings",
    headers=headers,
    json={
        "tag_value_id": tag_value_id,
        "resource_type": "project",
        "resource_id": "<project-uuid>",
    },
)
response.raise_for_status()
tagging_id = response.json()["id"]

Valid resource_type values: project, dataset, prompt, experiment, queue, deployment, dashboard, evaluator, mcp_server, fleet_integration.

Permissions: Assigning the Application tag only requires update access to the target resource, so editors can do this without workspaces:manage. Assigning any other tag key requires workspaces:manage.

Applying existing tags: If the key and value already exist (for example, the default Application key), retrieve their IDs first and go straight to the assign step:

tags = requests.get(
    f"{LANGSMITH_API_URL}/api/v1/workspaces/current/tags",
    headers=headers,
).json()
# tags is a list of {id, key, values: [{id, value}, ...]}

Query tags

# All tag keys and values in the workspace
tags = requests.get(
    f"{LANGSMITH_API_URL}/api/v1/workspaces/current/tags",
    headers=headers,
).json()

# Tags on a specific resource
resource_tags = requests.get(
    f"{LANGSMITH_API_URL}/api/v1/workspaces/current/tags/resource",
    headers=headers,
    params={"resource_type": "project", "resource_id": "<project-uuid>"},
).json()

# All resources tagged with a specific value
taggings = requests.get(
    f"{LANGSMITH_API_URL}/api/v1/workspaces/current/taggings",
    headers=headers,
    params={"tag_value_id": tag_value_id},
).json()

Remove a tag from a resource

requests.delete(
    f"{LANGSMITH_API_URL}/api/v1/workspaces/current/taggings/{tagging_id}",
    headers=headers,
)

Delete a tag key or value

# Delete a value (removes all resource assignments for that value)
requests.delete(
    f"{LANGSMITH_API_URL}/api/v1/workspaces/current/tag-keys/{tag_key_id}/tag-values/{tag_value_id}",
    headers=headers,
)

# Delete a key (also deletes all its values)
requests.delete(
    f"{LANGSMITH_API_URL}/api/v1/workspaces/current/tag-keys/{tag_key_id}",
    headers=headers,
)

For a full list of request/response fields, refer to the API reference.

---

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.