Tags

Tags let you filter and organize runs in the dashboard and via the SDK.

Overview

• Up to 10 tags per run
• Each tag: 1–128 characters
• Convention: prefix with type + underscore or colon — e.g., user_123456, video:123

Adding Tags

At Trigger Time

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

Inside the Run

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

export const myTask = task({
  id: "my-task",
  run: async (payload, { ctx }) => {
    // ctx.run.tags = tags set at trigger time (not updated mid-run)
    console.log(ctx.run.tags);

    // Add tags during execution
    await tags.add("product_1234567");
    await tags.add(["tag1", "tag2"]); // or pass array
  },
});

Tag limit

If adding tags would exceed 10 total, an error is logged and new tags are silently ignored.

Propagating Tags to Child Runs

Tags do not propagate automatically. Pass them explicitly:

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

Filtering by Tags

Dashboard

Runs page → Filter menu → Tags → type tag name → select.

SDK

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

// All completed runs tagged "user_123456"
for await (const run of runs.list({
  tag: "user_123456",
  status: ["COMPLETED"],
})) {
  console.log(run.id, run.taskIdentifier, run.finishedAt, run.tags);
}

Multiple tags (AND logic):

for await (const run of runs.list({
  tag: ["user_123456", "org_abcdefg"],
})) {
  // runs that have BOTH tags
}