---
title: "Tags"
description: "Tags allow you to easily filter runs in the dashboard and when using the SDK."
---

## What are tags?

We support up to 3 tags per run. Each one must be a string between 1 and 64 characters long.

We recommend prefixing your tags with their type and then an underscore or colon. For example, `user_123456` or `video:123`.

<Info>
  Many great APIs, like Stripe, already prefix their IDs with the type and an underscore. Like
  `cus_123456` for a customer.
</Info>

We don't enforce prefixes but if you use them you'll find it easier to filter and it will be clearer what the tag represents.

## How to add tags

There are two ways to add tags to a run:

1. When triggering the run.
2. Inside the `run` function, using `tags.add()`.

### 1. Adding tags when triggering the run

You can add tags when triggering a run using the `tags` option. All the different [trigger](/v3/triggering) methods support this.

<CodeGroup>

```ts trigger
const handle = await myTask.trigger(
  { message: "hello world" },
  { tags: ["user_123456", "org_abcdefg"] }
);
```

```ts batchTrigger
const batch = await myTask.batchTrigger([
  {
    payload: { message: "foo" },
    options: { tags: "product_123456" },
  },
  {
    payload: { message: "bar" },
    options: { tags: ["user_123456", "product_3456789"] },
  },
]);
```

</CodeGroup>

This will create a run with the tags `user_123456` and `org_abcdefg`. They look like this in the runs table:

![How tags appear in the dashboard](/images/tags-org-user.png)

### 2. Adding tags inside the `run` function

Use the `tags.add()` function to add tags to a run from inside the `run` function. This will add the tag `product_1234567` to the run:

```ts
import { task, tags } from "@trigger.dev/sdk/v3";

export const myTask = task({
  id: "my-task",
  run: async (payload: { message: string }, { ctx }) => {
    // Get the tags from when the run was triggered using the context
    // This is not updated if you add tags during the run
    logger.log("Tags from the run context", { tags: ctx.run.tags });

    // Add tags during the run (a single string or array of strings)
    await tags.add("product_1234567");
  },
});
```

Reminder: you can only have up to 3 tags per run. If you call `tags.add()` and the total number of tags will be more than 3 we log an error and ignore the new tags. That includes tags from triggering and from inside the run function.

### Propagating tags to child runs

Tags do not propagate to child runs automatically. By default runs have no tags and you have to set them explicitly.

It's easy to propagate tags if you want:

```ts
export const myTask = task({
  id: "my-task",
  run: async (payload: Payload, { ctx }) => {
    // Pass the tags from ctx into the child run
    const { id } = await otherTask.trigger(
      { message: "triggered from myTask" },
      { tags: ctx.run.tags }
    );
  },
});
```

## Filtering runs by tags

You can filter runs by tags in the dashboard and in the SDK.

### In the dashboard

On the Runs page open the filter menu, choose "Tags" and then start typing in the name of the tag you want to filter by. You can select it and it will restrict the results to only runs with that tag. You can add multiple tags to filter by more than one.

![Filter by tags](/images/tags-filtering.png)

### Using `runs.list()`

You can provide filters to the `runs.list` SDK function, including an array of tags.

```ts
import { runs } from "@trigger.dev/sdk/v3";

// Loop through all runs with the tag "user_123456" that have completed
for await (const run of runs.list({ tag: "user_123456", status: ["COMPLETED"] })) {
  console.log(run.id, run.taskIdentifier, run.finishedAt, run.tags);
}
```
