Task Definition API

Relevant source files

• packages/build/CHANGELOG.md
• packages/build/package.json
• packages/cli-v3/CHANGELOG.md
• packages/cli-v3/package.json
• packages/core/CHANGELOG.md
• packages/core/package.json
• packages/react-hooks/CHANGELOG.md
• packages/react-hooks/package.json
• packages/rsc/CHANGELOG.md
• packages/rsc/package.json
• packages/trigger-sdk/CHANGELOG.md
• packages/trigger-sdk/package.json

Purpose and Scope

This page documents the Task Definition API, which provides functions and types for defining background tasks in Trigger.dev. It covers the task() and schedules.task() functions, their configuration options including schemas, retry logic, queue settings, machine presets, and execution constraints.

For information about triggering tasks after they are defined, see Task Triggering and Scheduling. For details on lifecycle hooks that can be attached to tasks, see Lifecycle Hooks.

---

Core Task Definition Functions

Trigger.dev exports task definition functions from @trigger.dev/sdk/v3 (packages/trigger-sdk/src/v3/index.ts):

Task Definition Functions

Function	Export Path	Use Case	Type Safety	Schema Support
task()	@trigger.dev/sdk/v3	General-purpose tasks	TypeScript inference from run function	Optional jsonSchema parameter
schemaTask()	@trigger.dev/sdk/v3	Tasks requiring Zod schema validation	Full Zod type inference	Required Zod schema
toolTask()	N/A	Deprecated - Use ai.tool() instead	N/A	N/A

Sources: packages/trigger-sdk/package.json24-27 packages/trigger-sdk/CHANGELOG.md24-25 packages/trigger-sdk/CHANGELOG.md260-261

Task Definition to Runtime Flow

Sources: packages/trigger-sdk/package.json24-27 packages/core/package.json52-53

task() Function

The task() function is the general-purpose task definition API exported from @trigger.dev/sdk/v3. It infers TypeScript types from the run function signature and returns a Task<TPayload, TOutput> object with trigger methods.

Export Location: packages/trigger-sdk/package.json24-27 defines the export from ./src/v3/index.ts

Configuration Properties

Parameter	Type	Required	Description
id	string	Yes	Unique identifier for the task within the project
run	(payload: TInput, ctx: TaskContext) => Promise<TOutput>	Yes	The main execution function
init	(payload: TInput, ctx: TaskContext) => Promise<void>	No	Pre-execution initialization function
jsonSchema	JSONSchema	No	JSON Schema for payload type definition
retry	RetryOptions	No	Retry behavior configuration
queue	QueueOptions	No	Queue assignment and concurrency settings
machine	MachinePreset	No	Compute resource allocation preset
maxDuration	number	No	Maximum execution time in seconds
onStartAttempt	function	No	Hook called before each attempt starts
onSuccess	function	No	Hook called on successful completion
onFailure	function	No	Hook called on failure after all retries
onComplete	function	No	Hook called on completion (success or failure)

Lifecycle Hook Changes (v4.1.0):

• onStart deprecated - only fired before first attempt
• onStartAttempt added - fires before every attempt (including retries)
• onCancel added (v4.0.0-v4-beta.12) - fires when a run is cancelled

To replicate old onStart behavior with onStartAttempt:

Sources: packages/trigger-sdk/CHANGELOG.md48-83 packages/trigger-sdk/CHANGELOG.md304 packages/trigger-sdk/CHANGELOG.md589

schemaTask() Function

The schemaTask() function provides enhanced type safety through Zod schema validation. It automatically validates payloads at runtime and infers TypeScript types from the schema at compile-time.

Export Location:

• Main export: packages/trigger-sdk/package.json24-27 from ./src/v3/index.ts
• Types re-exported from @trigger.dev/core/v3 to prevent TypeScript error TS2742

Type Re-export Fix (v4.2.0): The schemaTask types are re-exported from @trigger.dev/core/v3 to prevent the TypeScript error "TS2742: The inferred type of 'task' cannot be named without a reference to '@trigger.dev/core/v3'."

Sources: packages/trigger-sdk/CHANGELOG.md24-25 packages/core/package.json29

Usage Example

Sources: packages/trigger-sdk/CHANGELOG.md24-25

---

Task Identification

Task ID

The id field is the only required configuration besides run. It must be unique within your project and is used to:

• Identify the task in the dashboard
• Reference the task when triggering from other code
• Track task versions across deployments

Task IDs support non-URL-friendly characters, but kebab-case or snake_case is recommended for consistency.

Sources: packages/trigger-sdk/CHANGELOG.md580

---

Run and Init Functions

The run Function

The run function contains the task's main execution logic. It receives two arguments:

1. payload: The input data passed when the task is triggered
2. ctx: Task execution context with metadata and utilities

Location: Defined in task configuration, executed by packages/core/src/v3/workers/taskExecutor.ts

Sources: packages/core/src/v3/workers/taskExecutor.ts packages/trigger-sdk/CHANGELOG.md217-230

TaskContext Object Properties

The ctx parameter (type: TaskContext) provides runtime information and utilities:

Property	Type	Added	Description
ctx.run.id	string	-	Unique identifier for this run
ctx.run.attempt.number	number	-	Current attempt number (starts at 1)
ctx.run.createdAt	Date	-	Timestamp when run was created
ctx.run.startedAt	Date	-	Timestamp when run started executing
ctx.run.parentTaskRunId	string | undefined	v4.0.0-beta.26	Parent run ID if triggered by another task
ctx.run.rootTaskRunId	string | undefined	v4.0.0-beta.26	Root run ID in the execution tree
ctx.run.version	string	v4.0.0-beta.0	Task version from deployment
ctx.task.id	string	-	The task's ID
ctx.environment.id	string	-	Environment ID
ctx.environment.type	string	-	Environment type (PRODUCTION, STAGING, DEVELOPMENT)
ctx.deployment.id	string	v4.0.0-beta.26	Deployment ID
ctx.deployment.version	string	v4.0.0-beta.26	Deployment version string

Hierarchical Task Relationships (v4.0.0-beta.26): The parentTaskRunId and rootTaskRunId properties support parent/child task relationships. For root runs (no parent), these properties work with metadata.root and metadata.parent:

Sources: packages/trigger-sdk/CHANGELOG.md427-440 packages/trigger-sdk/CHANGELOG.md603 packages/core/package.json29

The init Function

The init function is an optional pre-execution hook that runs before the run function. It's useful for:

• Loading configuration or credentials
• Establishing database connections
• Pre-warming caches
• Validating prerequisites

Key Characteristics:

• Runs once per task execution, before run()
• Has access to the same payload and ctx as run()
• Can be async
• Does not return a value (use for side effects only)
• Separate from onStartAttempt lifecycle hook (which runs before every retry attempt)

Sources: Based on task configuration patterns in the SDK

---

Schema Definition and Type Safety

Type Inference Approaches

Sources: packages/trigger-sdk/CHANGELOG.md14-15 packages/trigger-sdk/CHANGELOG.md389

Using Inline TypeScript Types

The simplest approach for tasks with well-defined internal types:

Sources: packages/trigger-sdk/src/v3/index.ts

Using Zod Schemas (Recommended)

For tasks that accept external input or require validation, use schemaTask():

Benefits:

• Automatic runtime validation
• Full TypeScript type inference
• Clear error messages for invalid payloads
• Self-documenting task interface

Sources: packages/trigger-sdk/CHANGELOG.md14-15 packages/core/src/v3/index.ts

Using JSON Schema

For integration with systems that use JSON Schema or non-Zod workflows:

Note: JSON Schema support is primarily used for AI SDK integration via ai.tool() (see AI Tool Integration section).

Sources: packages/trigger-sdk/CHANGELOG.md389 packages/trigger-sdk/CHANGELOG.md215

---

Retry Configuration

Tasks can be configured to automatically retry on failure with exponential backoff.

Retry Options

Retry Configuration Reference

Option	Type	Default	Description
maxAttempts	number	3	Maximum number of retry attempts (excluding first attempt)
factor	number	2	Exponential backoff multiplier
minTimeout	number	1000	Initial retry delay in milliseconds
maxTimeout	number	60000	Maximum retry delay in milliseconds
randomize	boolean	true	Add random jitter to retry delays

Retry Defaults Configuration

Tasks also support a retries.default option in task configuration used by internal error retry mechanics:

Sources: packages/core/CHANGELOG.md481-485

Error Handling and Retry Logic

The retry system (implementation in packages/core/package.json42 v3/utils/retries) distinguishes between error types:

Error Categories:

Error Type	Behavior	Example
Retryable	Automatic retry with backoff	Network errors, 500-level HTTP, 429 rate limits
Non-retryable	Immediate failure	400-level TriggerApiError, validation errors
System Failures	Special handling	Segfaults, FFmpeg OOM, Worker OOM

Special Error Detection:

• Segfaults: Detected and classified as system failures (v4.0.0-beta.3)
• FFmpeg OOM: Auto-detected via error messages (v3.3.15)
• Worker OOM: Can trigger automatic machine preset upgrade (v3.3.14)
• API Rate Limiting (429): Automatic retry with exponential backoff (v4.0.0-beta.0)

TriggerApiError Handling (v4.0.0-beta.7): 4xx errors from TriggerApiError are treated as non-retryable to prevent wasted retry attempts on client errors.

Sources: packages/cli-v3/CHANGELOG.md226 packages/trigger-sdk/CHANGELOG.md721-722 packages/trigger-sdk/CHANGELOG.md729-730 packages/core/CHANGELOG.md504-508

---

Queue Configuration

Queues allow you to control concurrency and organize tasks into execution groups.

Queue Options

Queue Configuration Properties

Property	Type	Description
name	string	Queue identifier (optional, defaults to task ID)
concurrencyLimit	number | null	Maximum concurrent runs in this queue

Concurrency Management and Run States

Concurrency Levels and Run Status States

Concurrency Consumption (v4.0.0-v4-beta.24):

Tasks consume concurrency tokens at two levels:

1. Environment-level: Global limit across all tasks in an environment
2. Queue-level: Limit specific to tasks in the same queue (when configured)

Burst Factor (v4.0.0-v4-beta.24): Environment concurrency limits include a "Burst Factor" (default 2.0x). If your environment limit is 100 and burst factor is 2.0x, you can execute up to 200 runs concurrently, but any single task/queue is still limited to 100.

Run Status Helpers (v4.0.0-v4-beta.24):

The SDK provides boolean helpers to check run states:

Concurrency Release Behavior (v4.0.0-v4-beta.24):

• Waitpoints: Concurrency NOT released when first blocked
• Checkpoints: Concurrency ALWAYS released when checkpointed and shutdown
• Queue Level: Both environment and queue concurrency released on checkpoint

Sources: packages/trigger-sdk/CHANGELOG.md456-497 packages/trigger-sdk/CHANGELOG.md263-267

---

Machine Presets

Machine presets control the compute resources allocated to task execution.

Available Machine Presets

Machine Preset Reference

Preset	vCPU	Memory	Use Case
micro	0.25	0.5 GB	Lightweight tasks
small-1x	0.5	1 GB	Standard tasks (default)
small-2x	1.0	2 GB	Moderate workloads
medium-1x	1.0	2 GB	Medium tasks
medium-2x	2.0	4 GB	Heavy tasks
large-1x	2.0	4 GB	Large tasks
large-2x	4.0	8 GB	Very large tasks

Machine presets can also be overridden at trigger time:

Sources: packages/trigger-sdk/CHANGELOG.md726-754 packages/trigger-sdk/CHANGELOG.md608

---

Maximum Duration

The maxDuration option sets a time limit for task execution. If a task exceeds this duration, it will be forcibly stopped.

• Type: number (seconds)
• Default: Varies by environment configuration
• Behavior: Task will transition to TIMED_OUT status if exceeded
• Configuration: Can be set at project level in trigger.config.ts

Sources: packages/trigger-sdk/CHANGELOG.md178 packages/core/CHANGELOG.md506-507 packages/cli-v3/CHANGELOG.md297

---

Scheduled Tasks

Scheduled tasks execute on a recurring schedule defined by a cron expression. They are managed by the internal ScheduleEngine system in internal-packages/schedule-engine/.

Export Location: packages/trigger-sdk/package.json24-27 exports schedules object from ./src/v3/index.ts

schedules.task() Architecture

Sources: packages/trigger-sdk/package.json24-27 Diagram inferred from schedule engine architecture

Example Usage

Sources: packages/trigger-sdk/src/v3/index.ts

Cron Expression Format

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
│ │ │ │ │
* * * * *

Common Patterns:

Pattern	Description
0 * * * *	Every hour
*/15 * * * *	Every 15 minutes
0 9 * * *	Daily at 9:00 AM
0 9 * * 1	Every Monday at 9:00 AM
0 0 1 * *	First day of every month at midnight
0 0 * * 0	Every Sunday at midnight

Cron Expression Utilities:

• Timezone: All cron expressions evaluated in UTC
• Parser Library: cronstrue package (v2.21.0) converts cron expressions to human-readable descriptions
• Dependency: packages/trigger-sdk/package.json57 lists "cronstrue": "^2.21.0"

Schedule Configuration and Storage

Scheduled tasks support all standard task configuration options:

Database Schema: Scheduled tasks are stored in PostgreSQL:

• TaskSchedule table: Stores schedule metadata and cron expressions
• BackgroundWorkerTask table: References the task definition
• TaskRun table: Each schedule execution creates a new run record

Schedule Engine Behavior:

• Continuous monitoring loop checks TaskSchedule records
• When schedule is due, creates new TaskRun with status DELAYED
• Run enters normal execution pipeline via RunEngine.DequeueSystem

Sources: packages/trigger-sdk/package.json57 Database schema inference from patterns

---

AI Tool Integration

Tasks can be converted to AI SDK tools, allowing language models to execute background tasks as function calls.

Location: packages/trigger-sdk/src/v3/ai.ts

ai.tool() Function

The ai.tool() function wraps a Trigger.dev task for use with the Vercel AI SDK as a tool.

Export Location: packages/trigger-sdk/package.json24-28 exports ai object from ./src/v3/ai.ts

Schema Extraction:

• schemaTask: Zod schema automatically extracted and converted to AI SDK format
• task with jsonSchema: JSON Schema used directly for tool parameter definition

Sources: packages/trigger-sdk/package.json38-40 (ai export), packages/trigger-sdk/CHANGELOG.md320-321

Using schemaTask with ai.tool()

The recommended approach uses schemaTask() for automatic schema conversion:

Sources: packages/trigger-sdk/CHANGELOG.md127 packages/trigger-sdk/src/v3/ai.ts

Using task with jsonSchema

For tasks defined with jsonSchema, the schema is used directly:

Sources: packages/trigger-sdk/CHANGELOG.md389 packages/trigger-sdk/CHANGELOG.md215

AI SDK 5.0 Support

Version Support (v4.0.0-v4-beta.28): Trigger.dev supports AI SDK 5.0. The ai.tool() function accepts:

• schemaTask() with Zod schemas
• task() with jsonSchema parameter

Peer Dependencies:

• packages/trigger-sdk/package.json81-83 declares "ai": "^4.2.0 || ^5.0.0" as optional peer dependency
• AI SDK is imported only when using ai.tool() functionality

Sources: packages/trigger-sdk/CHANGELOG.md320-321 packages/trigger-sdk/package.json81-83

Deprecated: toolTask()

The toolTask() function has been deprecated. Use the pattern above instead:

Sources: packages/trigger-sdk/CHANGELOG.md234 packages/trigger-sdk/CHANGELOG.md657

---

Task Registration and Runtime Behavior

Tasks move through multiple phases from developer code to production execution.

Task Lifecycle: Definition to Execution

Sources: packages/cli-v3/package.json33-34 (CLI binary), packages/core/package.json52 (worker exports)

Internal Registration Mechanisms

Task Discovery (Build Phase):

1. CLI scans directories specified in trigger.config.ts (default: ./trigger)
2. Module exports are analyzed for task() and schemaTask() calls
3. Task metadata (id, retry, queue, machine, cron) is extracted

Task Indexing (Deploy Phase):

1. trigger deploy command sends task metadata to platform API
2. Platform creates/updates BackgroundWorkerTask records in PostgreSQL
3. For scheduled tasks, creates/updates TaskSchedule records
4. Task version is associated with the deployment

Task Execution (Runtime):

1. TaskRun record created when task is triggered
2. RunEngine (in packages/core/package.json52) dequeues run
3. TaskExecutor class loads task module and invokes run() function
4. Lifecycle hooks (onStartAttempt, onSuccess, etc.) executed at appropriate points

Task Configuration Access: During execution, the TaskExecutor has access to:

• Task ID and metadata from BackgroundWorkerTask table
• Retry configuration for RunAttemptSystem
• Queue settings for concurrency management
• Machine preset for resource allocation

Sources: packages/core/package.json52-53 CLI deploy command architecture

Task Object API

The returned task object provides methods for triggering executions:

See Task Triggering and Scheduling for detailed documentation of these methods.

Sources: packages/trigger-sdk/src/v3/index.ts

---

Configuration Examples

Minimal Task

Fully Configured Task

Sources: packages/trigger-sdk/CHANGELOG.md26-57 packages/trigger-sdk/CHANGELOG.md401-414

---

Type Safety and Inference

TypeScript automatically infers types based on the task definition:

Sources: Based on TypeScript inference patterns common in the SDK

---

Summary

The Task Definition API provides a declarative way to define background jobs with:

• Simple syntax: Just id and run function required
• Type safety: Full TypeScript support with automatic inference
• Execution control: Retry logic, timeouts, resource allocation
• Concurrency management: Queue-based execution with limits
• Scheduling: Cron-based recurring tasks
• Integration: AI SDK tool support
• Extensibility: Lifecycle hooks for custom behavior (see Lifecycle Hooks)

Tasks defined with this API are automatically registered, versioned, and made available for triggering from anywhere in your application (see Task Triggering and Scheduling).

Sources: packages/trigger-sdk/package.json1-131 packages/trigger-sdk/CHANGELOG.md1-949