Triggering Tasks

Trigger Functions Reference

From your backend

Function	Description
tasks.trigger()	Triggers a task, returns a handle
tasks.batchTrigger()	Triggers a single task multiple times in a batch
batch.trigger()	Trigger multiple different tasks in a batch

From inside another task

Function	Description
yourTask.trigger()	Fire and forget — no result wait
yourTask.batchTrigger()	Trigger same task multiple times, no wait
yourTask.triggerAndWait()	Trigger and wait for result
yourTask.batchTriggerAndWait()	Trigger multiple times, wait for all
batch.triggerAndWait()	Batch trigger different tasks, wait for all
batch.triggerByTask()	Batch trigger by passing task instances
batch.triggerByTaskAndWait()	Batch trigger by task instances, wait

Triggering from Your Backend

Set TRIGGER_SECRET_KEY environment variable first. Use type-only imports for type safety:

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

export async function POST(request: Request) {
  const data = await request.json();
  const handle = await tasks.trigger<typeof emailSequence>("email-sequence", {
    to: data.email,
    name: data.name,
  });
  return Response.json(handle);
}

triggerAndWait()

Trigger a task and wait for the result (use inside another task):

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);
    } else {
      console.error("Error", result.error);
    }
  },
});

Use .unwrap() to get output directly or throw on failure:

const output = await childTask.triggerAndWait("some-data").unwrap();

Trigger Options

delay

await myTask.trigger({ some: "data" }, { delay: "1h" });
await myTask.trigger({ some: "data" }, { delay: "30m" });
await myTask.trigger({ some: "data" }, { delay: "88s" });
await myTask.trigger({ some: "data" }, { delay: new Date("2025-01-01T00:00:00Z") });

ttl (Time to Live)

Auto-expire the run if it hasn't started within the TTL:

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

idempotencyKey

Prevent duplicate runs:

const idempotencyKey = await idempotencyKeys.create("my-task-key");
await childTask.trigger(payload, { idempotencyKey });

debounce

Collapse multiple rapid triggers into one:

await myTask.trigger({ some: "data" }, {
  debounce: {
    key: "user-123",
    delay: "5s",
    mode: "trailing", // or "leading"
    maxDelay: "60s",
  }
});

queue

Override concurrency at trigger time:

const handle = await generatePullRequest.trigger(data, {
  queue: { name: "main-branch", concurrencyLimit: 10 },
});

concurrencyKey

Create per-user (or per-entity) queues:

const handle = await task.trigger(data, {
  queue: { name: "free-users", concurrencyLimit: 1 },
  concurrencyKey: data.userId,
});

maxAttempts

Override the retry count for this specific run:

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

region

await yourTask.trigger(payload, { region: "eu-central-1" });

machine

Override machine preset for this run:

await yourTask.trigger(payload, { machine: "large-1x" });

version

Pin to a specific deployment version:

await yourTask.trigger(payload, { version: "20250228.1" });

Streaming Batch Triggering

For large batches, pass an AsyncIterable or ReadableStream (SDK 4.3.1+):

async function* generateItems() {
  for (const userId of payload.userIds) {
    yield { payload: { userId } };
  }
}
const batchHandle = await myOtherTask.batchTrigger(generateItems());

Large Payloads

• Hard limit: 10MB
• > 512KB: Auto-uploaded to S3-compatible object store, URL stored in payload
• Task output limit: 100MB
• Larger payloads: Upload to your own storage and pass a presigned URL