Skip to main content

​
What are tags?

Tags are short string labels you attach to runs to categorize and filter them. Each run supports up to 10 tags, and each tag must be a string between 1 and 128 characters long. We recommend prefixing tags with their type followed by an underscore or colon. For example, user_123456 or video:123.
Many great APIs, like Stripe, already prefix IDs with the type and an underscore — for example, cus_123456 for a customer. Using the same convention with Trigger.dev tags makes them easy to recognize.
Prefixes are not enforced but make filtering faster and intent clearer.

​
Adding tags to a run

There are two ways to add tags:
  1. When triggering the run
  2. Inside the run function using tags.add()

​
When triggering

All trigger methods accept a tags option: 
import { myTask } from "./trigger/my-task";

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

​
Inside the run function

Use tags.add() to add tags after a run has started:
/trigger/my-task.ts
import { task, tags, logger } from "@trigger.dev/sdk";

export const myTask = task({
  id: "my-task",
  run: async (payload: { message: string }, { ctx }) => {
    // Tags set at trigger time are available in ctx
    // Note: ctx.run.tags is not updated when you call tags.add() mid-run
    logger.log("Tags from context", { tags: ctx.run.tags });

    // Add a tag during the run (accepts a string or array of strings)
    await tags.add("product_1234567");
  },
});
You can only have up to 10 tags per run. If calling tags.add() would push the total over 10, the SDK logs an error and ignores the new tags. This limit includes tags set at trigger time.

​
Propagating tags to child runs

Tags are not automatically inherited by child runs. You must pass them explicitly:
/trigger/my-task.ts
import { task } from "@trigger.dev/sdk";
import { otherTask } from "./other-task";

export const myTask = task({
  id: "my-task",
  run: async (payload: { message: string }, { ctx }) => {
    // Forward the parent's tags to the child run
    const { id } = await otherTask.trigger(
      { message: "triggered from myTask" },
      { tags: ctx.run.tags }
    );
  },
});

​
Filtering runs by tags

​
In the dashboard

On the Runs page, open the filter menu, choose Tags, and start typing the tag name. Select it to restrict results to runs with that tag. You can add multiple tags to filter by more than one at once.

​
Using runs.list()

Pass a tag filter (or an array of tags) to runs.list(): 
import { runs } from "@trigger.dev/sdk";

// Iterate over all completed runs tagged with "user_123456"
for await (const run of runs.list({ tag: "user_123456", status: ["COMPLETED"] })) {
  console.log(run.id, run.taskIdentifier, run.finishedAt, run.tags);
}
You can combine tag with any other supported filter — status, taskIdentifier, date ranges, and more. See the runs.list() reference for the full options.

​
Tag limits

ConstraintValue
Max tags per run10
Max tag length128 characters
Min tag length1 character
Tags are case-sensitive. User_123 and user_123 are treated as different tags.

Build docs developers (and LLMs) love

Get started for freeTalk to us