Run metadata

Attach a small amount of data to a run and update it as the run progresses.

Eric Allam

Eric Allam

CTO, Trigger.dev

Image for Run metadata

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 code
import { 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.

Ready to start building?

Build and deploy your first task in 3 minutes.

Get started now