​
Trigger functions

Trigger tasks from your backend:

FunctionWhat it does
tasks.trigger()Triggers a task and returns a handle you can use to fetch and manage the run.Docs
tasks.batchTrigger()Triggers a single task in a batch and returns a handle you can use to fetch and manage the runs.Docs
tasks.triggerAndPoll()Triggers a task and then polls the run until it’s complete.Docs
batch.trigger()Similar to tasks.batchTrigger but allows running multiple different tasksDocs

Trigger tasks from inside a another task:

FunctionWhat it does
yourTask.trigger()Triggers a task and gets a handle you can use to monitor and manage the run. It does not wait for the result.Docs
yourTask.batchTrigger()Triggers a task multiple times and gets a handle you can use to monitor and manage the runs. It does not wait for the results.Docs
yourTask.triggerAndWait()Triggers a task and then waits until it’s complete. You get the result data to continue with.Docs
yourTask.batchTriggerAndWait()Triggers a task multiple times in parallel and then waits until they’re all complete. You get the resulting data to continue with.Docs
batch.triggerAndWait()Similar to batch.trigger but will wait on the triggered tasks to finish and return the results.Docs
batch.triggerByTask()Similar to batch.trigger but allows passing in task instances instead of task IDs.Docs
batch.triggerByTaskAndWait()Similar to batch.triggerbyTask but will wait on the triggered tasks to finish and return the results.Docs

​
Triggering from your backend

When you trigger a task from your backend code, you need to set the TRIGGER_SECRET_KEY environment variable. You can find the value on the API keys page in the Trigger.dev dashboard. More info on API keys.

If you are using Next.js Server Actions you’ll need to be careful with bundling.

​
tasks.trigger()

Triggers a single run of a task with the payload you pass in, and any options you specify, without needing to import the task.

By using tasks.trigger(), you can pass in the task type as a generic argument, giving you full type checking. Make sure you use a type import so that your task code is not imported into your application.

Your backend
import { tasks } from "@trigger.dev/sdk/v3";
import type { emailSequence } from "~/trigger/emails";
//     👆 **type-only** import

//app/email/route.ts
export async function POST(request: Request) {
  //get the JSON from the request
  const data = await request.json();

  // Pass the task type to `trigger()` as a generic argument, giving you full type checking
  const handle = await tasks.trigger<typeof emailSequence>("email-sequence", {
    to: data.email,
    name: data.name,
  });

  //return a success response with the handle
  return Response.json(handle);
}

You can pass in options to the task using the second argument:

Your backend
import { tasks } from "@trigger.dev/sdk/v3";
import type { emailSequence } from "~/trigger/emails";

//app/email/route.ts
export async function POST(request: Request) {
  //get the JSON from the request
  const data = await request.json();

  // Pass the task type to `trigger()` as a generic argument, giving you full type checking
  const handle = await tasks.trigger<typeof emailSequence>(
    "email-sequence",
    {
      to: data.email,
      name: data.name,
    },
    { delay: "1h" } // 👈 Pass in the options here
  );

  //return a success response with the handle
  return Response.json(handle);
}

​
tasks.batchTrigger()

Triggers multiple runs of a single task with the payloads you pass in, and any options you specify, without needing to import the task.

Your backend
import { tasks } from "@trigger.dev/sdk/v3";
import type { emailSequence } from "~/trigger/emails";
//     👆 **type-only** import

//app/email/route.ts
export async function POST(request: Request) {
  //get the JSON from the request
  const data = await request.json();

  // Pass the task type to `batchTrigger()` as a generic argument, giving you full type checking
  const batchHandle = await tasks.batchTrigger<typeof emailSequence>(
    "email-sequence",
    data.users.map((u) => ({ payload: { to: u.email, name: u.name } }))
  );

  //return a success response with the handle
  return Response.json(batchHandle);
}

You can pass in options to the batchTrigger function using the second argument:

Your backend
import { tasks } from "@trigger.dev/sdk/v3";
import type { emailSequence } from "~/trigger/emails";

//app/email/route.ts
export async function POST(request: Request) {
  //get the JSON from the request
  const data = await request.json();

  // Pass the task type to `batchTrigger()` as a generic argument, giving you full type checking
  const batchHandle = await tasks.batchTrigger<typeof emailSequence>(
    "email-sequence",
    data.users.map((u) => ({ payload: { to: u.email, name: u.name } })),
    { idempotencyKey: "my-idempotency-key" } // 👈 Pass in the options here
  );

  //return a success response with the handle
  return Response.json(batchHandle);
}

You can also pass in options for each run in the batch:

Your backend
import { tasks } from "@trigger.dev/sdk/v3";
import type { emailSequence } from "~/trigger/emails";

//app/email/route.ts
export async function POST(request: Request) {
  //get the JSON from the request
  const data = await request.json();

  // Pass the task type to `batchTrigger()` as a generic argument, giving you full type checking
  const batchHandle = await tasks.batchTrigger<typeof emailSequence>(
    "email-sequence",
    data.users.map((u) => ({ payload: { to: u.email, name: u.name }, options: { delay: "1h" } })) // 👈 Pass in options to each item like so
  );

  //return a success response with the handle
  return Response.json(batchHandle);
}

​
tasks.triggerAndPoll()

Triggers a single run of a task with the payload you pass in, and any options you specify, and then polls the run until it’s complete.

We don’t recommend using triggerAndPoll(), especially inside a web request, as it will block the request until the run is complete. Please see our Realtime docs for a better way to handle this.

Your backend
import { tasks } from "@trigger.dev/sdk/v3";
import type { emailSequence } from "~/trigger/emails";

//app/email/route.ts
export async function POST(request: Request) {
  //get the JSON from the request
  const data = await request.json();

  // Pass the task type to `triggerAndPoll()` as a generic argument, giving you full type checking
  const result = await tasks.triggerAndPoll<typeof emailSequence>(
    "email-sequence",
    {
      to: data.email,
      name: data.name,
    },
    { pollIntervalMs: 5000 }
  );

  //return a success response with the result
  return Response.json(result);
}

​
batch.trigger()

Triggers multiple runs of different tasks with the payloads you pass in, and any options you specify. This is useful when you need to trigger multiple tasks at once.

Your backend
import { batch } from "@trigger.dev/sdk/v3";
import type { myTask1, myTask2 } from "~/trigger/myTasks";

export async function POST(request: Request) {
  //get the JSON from the request
  const data = await request.json();

  // Pass a union of the tasks to `trigger()` as a generic argument, giving you full type checking
  const result = await batch.trigger<typeof myTask1 | typeof myTask2>([
    // Because we're using a union, we can pass in multiple tasks by ID
    { id: "my-task-1", payload: { some: data.some } },
    { id: "my-task-2", payload: { other: data.other } },
  ]);

  //return a success response with the result
  return Response.json(result);
}

​
Triggering from inside another task

The following functions should only be used when running inside a task, for one of the following reasons:

  • You need to wait for the result of the triggered task.
  • You need to import the task instance. Importing a task instance from your backend code is not recommended, as it can pull in a lot of unnecessary code and dependencies.

​
yourTask.trigger()

Triggers a single run of a task with the payload you pass in, and any options you specify.

If you need to call trigger() on a task in a loop, use batchTrigger() instead which will trigger up to 500 runs in a single call.

./trigger/my-task.ts
import { myOtherTask, runs } from "~/trigger/my-other-task";

export const myTask = task({
  id: "my-task",
  run: async (payload: string) => {
    const handle = await myOtherTask.trigger({ foo: "some data" });

    const run = await runs.retrieve(handle);
    // Do something with the run
  },
});

To pass options to the triggered task, you can use the second argument:

./trigger/my-task.ts
import { myOtherTask, runs } from "~/trigger/my-other-task";

export const myTask = task({
  id: "my-task",
  run: async (payload: string) => {
    const handle = await myOtherTask.trigger({ foo: "some data" }, { delay: "1h" });

    const run = await runs.retrieve(handle);
    // Do something with the run
  },
});

​
yourTask.batchTrigger()

Triggers multiple runs of a single task with the payloads you pass in, and any options you specify.

/trigger/my-task.ts
import { myOtherTask, batch } from "~/trigger/my-other-task";

export const myTask = task({
  id: "my-task",
  run: async (payload: string) => {
    const batchHandle = await myOtherTask.batchTrigger([{ payload: "some data" }]);

    //...do other stuff
    const batch = await batch.retrieve(batchHandle.id);
  },
});

If you need to pass options to batchTrigger, you can use the second argument:

/trigger/my-task.ts
import { myOtherTask, batch } from "~/trigger/my-other-task";

export const myTask = task({
  id: "my-task",
  run: async (payload: string) => {
    const batchHandle = await myOtherTask.batchTrigger([{ payload: "some data" }], {
      idempotencyKey: "my-task-key",
    });

    //...do other stuff
    const batch = await batch.retrieve(batchHandle.id);
  },
});

You can also pass in options for each run in the batch:

/trigger/my-task.ts
import { myOtherTask, batch } from "~/trigger/my-other-task";

export const myTask = task({
  id: "my-task",
  run: async (payload: string) => {
    const batchHandle = await myOtherTask.batchTrigger([
      { payload: "some data", options: { delay: "1h" } },
    ]);

    //...do other stuff
    const batch = await batch.retrieve(batchHandle.id);
  },
});

​
yourTask.triggerAndWait()

This is where it gets interesting. You can trigger a task and then wait for the result. This is useful when you need to call a different task and then use the result to continue with your task.

/trigger/parent.ts
export const parentTask = task({
  id: "parent-task",
  run: async (payload: string) => {
    const result = await childTask.triggerAndWait("some-data");
    console.log("Result", result);

    //...do stuff with the result
  },
});

The result object is a “Result” type that needs to be checked to see if the child task run was successful:

/trigger/parent.ts
export const parentTask = task({
  id: "parent-task",
  run: async (payload: string) => {
    const result = await childTask.triggerAndWait("some-data");

    if (result.ok) {
      console.log("Result", result.output); // result.output is the typed return value of the child task
    } else {
      console.error("Error", result.error); // result.error is the error that caused the run to fail
    }
  },
});

If instead you just want to get the output of the child task, and throw an error if the child task failed, you can use the unwrap method:

/trigger/parent.ts
export const parentTask = task({
  id: "parent-task",
  run: async (payload: string) => {
    const output = await childTask.triggerAndWait("some-data").unwrap();
    console.log("Output", output);
  },
});

You can also catch the error if the child task fails and get more information about the error:

/trigger/parent.ts
import { task, SubtaskUnwrapError } from "@trigger.dev/sdk/v3";
export const parentTask = task({
  id: "parent-task",
  run: async (payload: string) => {
    try {
      const output = await childTask.triggerAndWait("some-data").unwrap();
      console.log("Output", output);
    } catch (error) {
      if (error instanceof SubtaskUnwrapError) {
        console.error("Error in fetch-post-task", {
          runId: error.runId,
          taskId: error.taskId,
          cause: error.cause,
        });
      }
    }
  },
});

This method should only be used inside a task. If you use it outside a task, it will throw an error.

​
yourTask.batchTriggerAndWait()

You can batch trigger a task and wait for all the results. This is useful for the fan-out pattern, where you need to call a task multiple times and then wait for all the results to continue with your task.

/trigger/nested.ts
export const batchParentTask = task({
  id: "parent-task",
  run: async (payload: string) => {
    const results = await childTask.batchTriggerAndWait([
      { payload: "item4" },
      { payload: "item5" },
      { payload: "item6" },
    ]);
    console.log("Results", results);

    //...do stuff with the result
  },
});

This method should only be used inside a task. If you use it outside a task, it will throw an error.

​
batch.triggerAndWait()

You can batch trigger multiple different tasks and wait for all the results:

/trigger/batch.ts
import { batch, task } from "@trigger.dev/sdk/v3";

export const parentTask = task({
  id: "parent-task",
  run: async (payload: string) => {
    //                                         👇 Pass a union of all the tasks you want to trigger
    const results = await batch.triggerAndWait<typeof childTask1 | typeof childTask2>([
      { id: "child-task-1", payload: { foo: "World" } }, // 👈 The payload is typed correctly based on the task `id`
      { id: "child-task-2", payload: { bar: 42 } }, // 👈 The payload is typed correctly based on the task `id`
    ]);

    for (const result of results) {
      if (result.ok) {
        // 👇 Narrow the type of the result based on the taskIdentifier
        switch (result.taskIdentifier) {
          case "child-task-1":
            console.log("Child task 1 output", result.output); // 👈 result.output is typed as a string
            break;
          case "child-task-2":
            console.log("Child task 2 output", result.output); // 👈 result.output is typed as a number
            break;
        }
      } else {
        console.error("Error", result.error); // 👈 result.error is the error that caused the run to fail
      }
    }
  },
});

export const childTask1 = task({
  id: "child-task-1",
  run: async (payload: { foo: string }) => {
    return `Hello ${payload}`;
  },
});

export const childTask2 = task({
  id: "child-task-2",
  run: async (payload: { bar: number }) => {
    return bar + 1;
  },
});

​
batch.triggerByTask()

You can batch trigger multiple different tasks by passing in the task instances. This function is especially useful when you have a static set of tasks you want to trigger:

/trigger/batch.ts
import { batch, task, runs } from "@trigger.dev/sdk/v3";

export const parentTask = task({
  id: "parent-task",
  run: async (payload: string) => {
    const results = await batch.triggerByTask([
      { task: childTask1, payload: { foo: "World" } }, // 👈 The payload is typed correctly based on the task instance
      { task: childTask2, payload: { bar: 42 } }, // 👈 The payload is typed correctly based on the task instance
    ]);

    // 👇 results.runs is a tuple, allowing you to get type safety without needing to narrow
    const run1 = await runs.retrieve(results.runs[0]); // 👈 run1 is typed as the output of childTask1
    const run2 = await runs.retrieve(results.runs[1]); // 👈 run2 is typed as the output of childTask2
  },
});

export const childTask1 = task({
  id: "child-task-1",
  run: async (payload: { foo: string }) => {
    return `Hello ${payload}`;
  },
});

export const childTask2 = task({
  id: "child-task-2",
  run: async (payload: { bar: number }) => {
    return bar + 1;
  },
});

​
batch.triggerByTaskAndWait()

You can batch trigger multiple different tasks by passing in the task instances, and wait for all the results. This function is especially useful when you have a static set of tasks you want to trigger:

/trigger/batch.ts
import { batch, task, runs } from "@trigger.dev/sdk/v3";

export const parentTask = task({
  id: "parent-task",
  run: async (payload: string) => {
    const { runs } = await batch.triggerByTaskAndWait([
      { task: childTask1, payload: { foo: "World" } }, // 👈 The payload is typed correctly based on the task instance
      { task: childTask2, payload: { bar: 42 } }, // 👈 The payload is typed correctly based on the task instance
    ]);

    if (runs[0].ok) {
      console.log("Child task 1 output", runs[0].output); // 👈 runs[0].output is typed as the output of childTask1
    }

    if (runs[1].ok) {
      console.log("Child task 2 output", runs[1].output); // 👈 runs[1].output is typed as the output of childTask2
    }

    // 💭 A nice alternative syntax is to destructure the runs array:
    const {
      runs: [run1, run2],
    } = await batch.triggerByTaskAndWait([
      { task: childTask1, payload: { foo: "World" } }, // 👈 The payload is typed correctly based on the task instance
      { task: childTask2, payload: { bar: 42 } }, // 👈 The payload is typed correctly based on the task instance
    ]);

    if (run1.ok) {
      console.log("Child task 1 output", run1.output); // 👈 run1.output is typed as the output of childTask1
    }

    if (run2.ok) {
      console.log("Child task 2 output", run2.output); // 👈 run2.output is typed as the output of childTask2
    }
  },
});

export const childTask1 = task({
  id: "child-task-1",
  run: async (payload: { foo: string }) => {
    return `Hello ${payload}`;
  },
});

export const childTask2 = task({
  id: "child-task-2",
  run: async (payload: { bar: number }) => {
    return bar + 1;
  },
});

​
Triggering from your frontend

If you want to trigger a task directly from a frontend application, you can use our React hooks.

​
Options

All of the above functions accept an options object:

await myTask.trigger({ some: "data" }, { delay: "1h", ttl: "1h" });
await myTask.batchTrigger([{ payload: { some: "data" }, options: { delay: "1h" } }]);

The following options are available:

​
delay

When you want to trigger a task now, but have it run at a later time, you can use the delay option:

// Delay the task run by 1 hour
await myTask.trigger({ some: "data" }, { delay: "1h" });
// Delay the task run by 88 seconds
await myTask.trigger({ some: "data" }, { delay: "88s" });
// Delay the task run by 1 hour and 52 minutes and 18 seconds
await myTask.trigger({ some: "data" }, { delay: "1h52m18s" });
// Delay until a specific time
await myTask.trigger({ some: "data" }, { delay: "2024-12-01T00:00:00" });
// Delay using a Date object
await myTask.trigger({ some: "data" }, { delay: new Date(Date.now() + 1000 * 60 * 60) });
// Delay using a timezone
await myTask.trigger({ some: "data" }, { delay: new Date("2024-07-23T11:50:00+02:00") });

Runs that are delayed and have not been enqueued yet will display in the dashboard with a “Delayed” status:

Delayed runs will be enqueued at the time specified, and will run as soon as possible after that time, just as a normally triggered run would.

You can cancel a delayed run using the runs.cancel SDK function:

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

await runs.cancel("run_1234");

You can also reschedule a delayed run using the runs.reschedule SDK function:

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

// The delay option here takes the same format as the trigger delay option
await runs.reschedule("run_1234", { delay: "1h" });

The delay option is also available when using batchTrigger:

await myTask.batchTrigger([{ payload: { some: "data" }, options: { delay: "1h" } }]);

​
ttl

You can set a TTL (time to live) when triggering a task, which will automatically expire the run if it hasn’t started within the specified time. This is useful for ensuring that a run doesn’t get stuck in the queue for too long.

All runs in development have a default ttl of 10 minutes. You can disable this by setting the ttl option.

import { myTask } from "./trigger/myTasks";

// Expire the run if it hasn't started within 1 hour
await myTask.trigger({ some: "data" }, { ttl: "1h" });

// If you specify a number, it will be treated as seconds
await myTask.trigger({ some: "data" }, { ttl: 3600 }); // 1 hour

When a run is expired, it will be marked as “Expired” in the dashboard:

When you use both delay and ttl, the TTL will start counting down from the time the run is enqueued, not from the time the run is triggered.

So for example, when using the following code:

await myTask.trigger({ some: "data" }, { delay: "10m", ttl: "1h" });

The timeline would look like this:

  1. The run is created at 12:00:00
  2. The run is enqueued at 12:10:00
  3. The TTL starts counting down from 12:10:00
  4. If the run hasn’t started by 13:10:00, it will be expired

For this reason, the ttl option only accepts durations and not absolute timestamps.

​
idempotencyKey

You can provide an idempotencyKey to ensure that a task is only triggered once with the same key. This is useful if you are triggering a task within another task that might be retried:

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

export const myTask = task({
  id: "my-task",
  retry: {
    maxAttempts: 4,
  },
  run: async (payload: any) => {
    // By default, idempotency keys generated are unique to the run, to prevent retries from duplicating child tasks
    const idempotencyKey = await idempotencyKeys.create("my-task-key");

    // childTask will only be triggered once with the same idempotency key
    await childTask.trigger(payload, { idempotencyKey });

    // Do something else, that may throw an error and cause the task to be retried
  },
});

For more information, see our Idempotency documentation.

In version 3.3.0 and later, the idempotencyKey option is not available when using triggerAndWait or batchTriggerAndWait, due to a bug that would sometimes cause the parent task to become stuck. We are working on a fix for this issue.

​
idempotencyKeyTTL

Idempotency keys automatically expire after 30 days, but you can set a custom TTL for an idempotency key when triggering a task:

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

export const myTask = task({
  id: "my-task",
  retry: {
    maxAttempts: 4,
  },
  run: async (payload: any) => {
    // By default, idempotency keys generated are unique to the run, to prevent retries from duplicating child tasks
    const idempotencyKey = await idempotencyKeys.create("my-task-key");

    // childTask will only be triggered once with the same idempotency key
    await childTask.trigger(payload, { idempotencyKey, idempotencyKeyTTL: "1h" });

    // Do something else, that may throw an error and cause the task to be retried
  },
});

For more information, see our Idempotency documentation.

​
queue

When you trigger a task you can override the concurrency limit. This is really useful if you sometimes have high priority runs.

The task:

/trigger/override-concurrency.ts
const generatePullRequest = task({
  id: "generate-pull-request",
  queue: {
    //normally when triggering this task it will be limited to 1 run at a time
    concurrencyLimit: 1,
  },
  run: async (payload) => {
    //todo generate a PR using OpenAI
  },
});

Triggering from your backend and overriding the concurrency:

app/api/push/route.ts
import { generatePullRequest } from "~/trigger/override-concurrency";

export async function POST(request: Request) {
  const data = await request.json();

  if (data.branch === "main") {
    //trigger the task, with a different queue
    const handle = await generatePullRequest.trigger(data, {
      queue: {
        //the "main-branch" queue will have a concurrency limit of 10
        //this triggered run will use that queue
        name: "main-branch",
        concurrencyLimit: 10,
      },
    });

    return Response.json(handle);
  } else {
    //triggered with the default (concurrency of 1)
    const handle = await generatePullRequest.trigger(data);
    return Response.json(handle);
  }
}

​
concurrencyKey

If you’re building an application where you want to run tasks for your users, you might want a separate queue for each of your users. (It doesn’t have to be users, it can be any entity you want to separately limit the concurrency for.)

You can do this by using concurrencyKey. It creates a separate queue for each value of the key.

Your backend code:

app/api/pr/route.ts
import { generatePullRequest } from "~/trigger/override-concurrency";

export async function POST(request: Request) {
  const data = await request.json();

  if (data.isFreeUser) {
    //free users can only have 1 PR generated at a time
    const handle = await generatePullRequest.trigger(data, {
      queue: {
        //every free user gets a queue with a concurrency limit of 1
        name: "free-users",
        concurrencyLimit: 1,
      },
      concurrencyKey: data.userId,
    });

    //return a success response with the handle
    return Response.json(handle);
  } else {
    //trigger the task, with a different queue
    const handle = await generatePullRequest.trigger(data, {
      queue: {
        //every paid user gets a queue with a concurrency limit of 10
        name: "paid-users",
        concurrencyLimit: 10,
      },
      concurrencyKey: data.userId,
    });

    //return a success response with the handle
    return Response.json(handle);
  }
}

​
maxAttempts

You can set the maximum number of attempts for a task run. If the run fails, it will be retried up to the number of attempts you specify.

await myTask.trigger({ some: "data" }, { maxAttempts: 3 });
await myTask.trigger({ some: "data" }, { maxAttempts: 1 }); // no retries

This will override the retry.maxAttempts value set in the task definition.

​
tags

View our tags doc for more information.

​
metadata

View our metadata doc for more information.

​
maxDuration

View our maxDuration doc for more information.

​
Large Payloads

We recommend keeping your task payloads as small as possible. We currently have a hard limit on task payloads above 10MB.

If your payload size is larger than 512KB, instead of saving the payload to the database, we will upload it to an S3-compatible object store and store the URL in the database.

When your task runs, we automatically download the payload from the object store and pass it to your task function. We also will return to you a payloadPresignedUrl from the runs.retrieve SDK function so you can download the payload if needed:

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

const run = await runs.retrieve(handle);

if (run.payloadPresignedUrl) {
  const response = await fetch(run.payloadPresignedUrl);
  const payload = await response.json();

  console.log("Payload", payload);
}

We also use this same system for dealing with large task outputs, and subsequently will return a corresponding outputPresignedUrl. Task outputs are limited to 100MB.

If you need to pass larger payloads, you’ll need to upload the payload to your own storage and pass a URL to the file in the payload instead. For example, uploading to S3 and then sending a presigned URL that expires in URL:

​
Batch Triggering

When using triggering a batch, the total size of all payloads cannot exceed 1MB. This means if you are doing a batch of 100 runs, each payload should be less than 100KB. The max batch size is 500 runs.

Was this page helpful?

Scheduled tasks (cron)Runs