tasks

Trigger.dev Tasks

Build durable background tasks that run reliably with automatic retries, queuing, and observability.

When to Use

Creating background jobs or async workflows
Building AI agents that need long-running execution
Processing webhooks, emails, or file uploads
Scheduling recurring tasks (cron)
Any work that shouldn't block your main application

Critical Rules

Always use @trigger.dev/sdk — never use deprecated client.defineJob
Check result.ok before accessing result.output from triggerAndWait()
Never use Promise.all with triggerAndWait() or wait.* calls
Export tasks from files in your trigger/ directory

Basic Task

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

export const processData = task({ id: "process-data", retry: { maxAttempts: 10, factor: 1.8, minTimeoutInMs: 500, maxTimeoutInMs: 30_000, }, run: async (payload: { userId: string; data: any[] }) => { console.log(Processing ${payload.data.length} items); return { processed: payload.data.length }; }, });

Schema Task (Validated Input)

import { schemaTask } from "@trigger.dev/sdk"; import { z } from "zod";

export const validatedTask = schemaTask({ id: "validated-task", schema: z.object({ name: z.string(), email: z.string().email(), }), run: async (payload) => { // payload is typed and validated return { message: Hello ${payload.name} }; }, });

Triggering Tasks

From Backend Code

import { tasks } from "@trigger.dev/sdk"; import type { processData } from "./trigger/tasks";

// Single trigger (fire and forget) const handle = await tasks.trigger<typeof processData>("process-data", { userId: "123", data: [{ id: 1 }], });

// Batch trigger (up to 1,000 items, 3MB per payload) const batchHandle = await tasks.batchTrigger<typeof processData>("process-data", [ { payload: { userId: "123", data: [] } }, { payload: { userId: "456", data: [] } }, ]);

From Inside Tasks

export const parentTask = task({ id: "parent-task", run: async (payload) => { // Fire and forget const handle = await childTask.trigger({ data: "value" });

// Wait for result - returns Result object, NOT direct output
const result = await childTask.triggerAndWait({ data: "value" });
if (result.ok) {
  console.log("Output:", result.output);
} else {
  console.error("Failed:", result.error);
}

// Quick unwrap (throws on error)
const output = await childTask.triggerAndWait({ data: "value" }).unwrap();

// Batch with wait
const results = await childTask.batchTriggerAndWait([
  { payload: { data: "item1" } },
  { payload: { data: "item2" } },
]);

}, });

Waits

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

export const taskWithWaits = task({ id: "task-with-waits", run: async (payload) => { await wait.for({ seconds: 30 }); await wait.for({ minutes: 5 }); await wait.until({ date: new Date("2024-12-25") });

// Wait for external approval
await wait.forToken({
  token: "user-approval-token",
  timeoutInSeconds: 3600,
});

}, });

Waits > 5 seconds are checkpointed and don't count toward compute.

Concurrency & Queues

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

// Shared queue const emailQueue = queue({ name: "email-processing", concurrencyLimit: 5, });

// Task-level concurrency export const oneAtATime = task({ id: "sequential-task", queue: { concurrencyLimit: 1 }, run: async (payload) => { // Only one instance runs at a time }, });

// Use shared queue export const emailTask = task({ id: "send-email", queue: emailQueue, run: async (payload) => {}, });

// Per-tenant concurrency (at trigger time) await childTask.trigger(payload, { queue: { name: user-${userId}, concurrencyLimit: 2, }, });

Debouncing

Consolidate rapid triggers into a single execution:

await myTask.trigger( { userId: "123" }, { debounce: { key: "user-123-update", delay: "5s", mode: "trailing", // Use latest payload (default: "leading") }, } );

Idempotency

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

export const paymentTask = task({ id: "process-payment", run: async (payload: { orderId: string }) => { const key = await idempotencyKeys.create(payment-${payload.orderId});

await chargeCustomer.trigger(payload, {
  idempotencyKey: key,
  idempotencyKeyTTL: "24h",
});

}, });

Error Handling & Retries

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

export const resilientTask = task({ id: "resilient-task", retry: { maxAttempts: 10, factor: 1.8, minTimeoutInMs: 500, maxTimeoutInMs: 30_000, }, catchError: async ({ error, ctx }) => { if (error.code === "FATAL_ERROR") { throw new AbortTaskRunError("Cannot retry"); } return { retryAt: new Date(Date.now() + 60000) }; }, run: async (payload) => { // Retry specific operations const result = await retry.onThrow( async () => unstableApiCall(payload), { maxAttempts: 3 } );

// HTTP retries with conditions
const response = await retry.fetch("https://api.example.com", {
  retry: {
    maxAttempts: 5,
    condition: (res, err) => res?.status === 429 || res?.status >= 500,
  },
});

}, });

Scheduled Tasks (Cron)

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

// Declarative schedule export const dailyTask = schedules.task({ id: "daily-cleanup", cron: "0 0 * * *", // Midnight UTC run: async (payload) => { // payload.timestamp - scheduled time // payload.timezone - IANA timezone // payload.scheduleId - schedule identifier }, });

// With timezone export const tokyoTask = schedules.task({ id: "tokyo-morning", cron: { pattern: "0 9 * * *", timezone: "Asia/Tokyo" }, run: async () => {}, });

// Dynamic/multi-tenant schedules await schedules.create({ task: "reminder-task", cron: "0 8 * * *", timezone: "America/New_York", externalId: userId, deduplicationKey: ${userId}-daily, });

Metadata & Progress

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

export const batchProcessor = task({ id: "batch-processor", run: async (payload: { items: any[] }) => { metadata.set("progress", 0).set("total", payload.items.length);

for (let i = 0; i &#x3C; payload.items.length; i++) {
  await processItem(payload.items[i]);
  metadata.set("progress", ((i + 1) / payload.items.length) * 100);
}

metadata.set("status", "completed");

}, });

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

trigger-tasks

trigger-config

trigger-agents

trigger-setup