You can now attach up to 4KB (4,096 bytes) of metadata to a run, which you can then access from inside the run function, via the API, and in the dashboard. You can use metadata to store additional, structured information on a run. For example, you could use metadata to update the progress of a run.
Usage
Add metadata to a run by passing it as an object to the trigger function:
const handle = await myTask.trigger( { message: "hello world" }, { metadata: { user: { name: "Eric", id: "user_1234" } } });
Then inside your run function, you can access the metadata like this:
import { task, metadata } from "@trigger.dev/sdk/v3";export const myTask = task({ id: "my-task", run: async (payload: { message: string }) => { const user = metadata.get("user"); console.log(user.name); // "Eric" console.log(user.id); // "user_1234" },});
You can also update the metadata during the run:
import { task, metadata } from "@trigger.dev/sdk/v3";export const myTask = task({ id: "my-task", run: async (payload: { message: string }) => { // Do some work await metadata.set("status", { state: "running", progress: 0.1, message: "Starting", }); // Do some more work await metadata.set("status", { state: "running", progress: 0.5, message: "Halfway there", }); // Do even more work await metadata.set("status", { state: "running", progress: 0.9, message: "Almost done", }); // Finish up await metadata.set("status", { state: "complete", progress: 1, message: "Done", }); },});
Access the metadata outside of a task via the API:
// Somewhere in your backend codeimport { runs } from "@trigger.dev/sdk/v3";async function main() { const run = await runs.retrieve("run_1234"); console.log(run.metadata.user.name); // "Eric" console.log(run.metadata.user.id); // "user_1234"}
Learn all about how to use metadata in the metadata documentation.
Updating
Run metadata is available as of version 3.0.8 of the SDK. To update, run:
npx trigger.dev@latest update
If you are self-hosting Trigger.dev, you will need to update to version 3.0.8 or later. See our self-hosting updating docs for more information.