---
updatedAt: 2026-08-20T10:52:00.000Z
agentTools:
  projectIndex: https://docs.hud.io/llms.txt
---

# Tagging and Filtering Your Data in Hud

**Use custom tags to slice your metrics and focus on the service sessions that matter to you.**

<br />

### 1. Add Tags in Your SDK Configuration

Tags are defined in your SDK initialization block as key-value pairs. All metrics sent from that service session will carry those tags.

#### Tags Format

```node
import * as hud from 'hud-sdk/setup';

hud.initSession(
  "<API_KEY>",
  "<Service>",
  {
    tags: {
      "region": "us-east",
      "job": "worker-A",
      "language": "node"
    },
  }
);
```
```python
import hud_sdk

hud_sdk.init_session(
  "<API_KEY>",
  "<Service>",
  tags={
    "region": "us-east",
    "job": "worker-A",
    "language": "python"
  }
)
```
```Text Java
java -javaagent:./hud-sdk.jar \
  -Dio.hud.tags.region=us-east \
  -Dio.hud.tags.job=worker-A \
  -Dio.hud.tags.language=java \
  -jar [app.jar]
```

Note:

* You can use any string key and string value.
* Tags are sent once per session and apply to all metrics from that session.
* In Java, tags are passed as `-Dio.hud.tags.<key>=<value>` system properties rather than in an init block, since the agent is attached at startup. A `.` in a tag key is replaced with `_`.

<br />

***

<br />

### 2. Filter Data in the Hud Web App and MCP Tools

<br />

#### Web App

Once you've run your service with tags, you can use the **Tag** filter at the top of any metrics page (Overview, Endpoints, Functions, Queues).

* Select one or more tag keys (e.g., "region") -> Then choose values (e.g., "us-east", "eu-west")

Note:

* Filters are reflected in the URL and persist as you navigate
* You’ll only see metrics from sessions that match **all** selected tags
* You can only filter by tags that were seen in one of your service sessions within the last 6 months. If no recent tags exist, the filter selector will not appear.

<br />

#### MCP Tools

If you're using Hud in your IDE, your agent can request filtered results using the same tag values.

* Just ask your agent to request metrics for a specific tag or tag combination.
  * For example:
    > Show me the top endpoints for region=us-east and job=worker-A
* Your agent will automatically request the matching data from Hud MCP with the relevant tag filters. Note: If no tag filters are passed, all data is returned.

<br />

***

### FAQ

**Q: Can I add tags dynamically at runtime?**

A: Not yet. Tags must be set when initializing the SDK.

**Q: Are filters case-sensitive?**

A: No. Tag keys and values are matched in a case-insensitive way.

**Q: Where can I see which tags are active in my account?**

A: All detected tags will show up in the tag filter UI in the web app.

***

Need help? <Anchor label="Contact us →" target="_blank" href="https://www.app.hud.io/?support_chat=true">Contact us →</Anchor>