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

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

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.

There are two ways to add tags to a run:

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

You can add tags when triggering a run using the tags option. All the different trigger methods support this.

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

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

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

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:

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

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 10 tags per run. If you call tags.add() and the total number of tags will be more than 10 we log an error and ignore the new tags. That includes tags from triggering and from inside the run function.

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:

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 }
    );
  },
});

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

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.

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

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

// 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);
}