This document covers the mechanisms for triggering task execution and scheduling tasks to run at specific times. It describes the SDK methods available for triggering tasks (trigger(), triggerAndWait(), batchTrigger(), etc.), the options that can be passed when triggering, and the scheduling API for recurring tasks using cron patterns.
For information about defining tasks themselves, see Task Definition API. For lifecycle hooks that execute during task runs, see Lifecycle Hooks.
trigger()The trigger() method initiates a task run asynchronously and immediately returns a handle containing the run ID. This is a "fire and forget" pattern where the caller does not wait for task completion.
Sources: packages/trigger-sdk/CHANGELOG.md13-14 packages/trigger-sdk/CHANGELOG.md743-770
triggerAndWait()The triggerAndWait() method triggers a task and waits for it to complete, returning the task output. This creates a parent-child relationship between runs.
The waiting run enters a WAITING state and releases concurrency slots until the child completes.
Sources: packages/trigger-sdk/CHANGELOG.md749-750 packages/trigger-sdk/CHANGELOG.md252-295
batchTrigger()The batchTrigger() method triggers multiple runs of the same task in a single request. It supports up to 500 runs per batch and returns handles for all triggered runs.
Batch items can have individual options including idempotency keys and machine presets.
Sources: packages/trigger-sdk/CHANGELOG.md860-884 packages/trigger-sdk/CHANGELOG.md869-879
batch.trigger()The batch.trigger() and batch.triggerByTask() methods allow triggering multiple different tasks in a single batch request.
These methods return type-safe results that can be checked for success or failure:
Sources: packages/trigger-sdk/CHANGELOG.md887-465
tasks.trigger()The tasks namespace provides methods to trigger tasks by their string ID rather than by task reference:
This is useful when the task reference is not available at compile time.
Sources: packages/trigger-sdk/CHANGELOG.md761-770
Idempotency keys prevent duplicate task execution when requests are retried. Each key is unique within an environment and expires after 24 hours by default.
If the same key is used within the TTL period, the original run handle is returned instead of creating a new run. Idempotency keys were removed from triggerAndWait() to prevent permanently frozen runs.
Sources: packages/trigger-sdk/CHANGELOG.md866-883 packages/core/CHANGELOG.md371-384
The machine option allows overriding the task's default machine preset at trigger time:
Valid machine presets include "micro", "small-1x", "small-2x", "medium-1x", "large-1x", etc.
Sources: packages/trigger-sdk/CHANGELOG.md742-770 packages/core/CHANGELOG.md283-310
Tasks can be scheduled to run at a future time using the delay option or by setting a queueTimestamp:
Runs with future queue timestamps enter the DELAYED status until their scheduled time.
Sources: packages/core/src/v3/schemas/api.ts packages/core/CHANGELOG.md271
Tags enable grouping and filtering runs, while metadata allows storing up to 4KB of custom data:
Sources: packages/core/CHANGELOG.md536-537 packages/trigger-sdk/CHANGELOG.md786-787
The region option allows specifying a deployment region override when triggering:
Sources: packages/trigger-sdk/CHANGELOG.md299 packages/core/CHANGELOG.md408
| Option | Type | Description |
|---|---|---|
idempotencyKey | string | Unique key to prevent duplicate runs |
idempotencyKeyTTL | string | Expiration time for idempotency key (default: 24h) |
machine | string | Machine preset override |
delay | string | Delay before execution (e.g., "5m", "1h") |
tags | string[] | Tags for grouping and filtering |
metadata | Record<string, any> | Custom metadata (max 4KB) |
region | string | Region override for deployment |
queue | object | Queue-specific options |
Sources: packages/core/src/v3/schemas/api.ts apps/webapp/app/v3/services/triggerTask.server.ts16-36
The schedules.task() method creates tasks that run on a recurring schedule defined by cron patterns:
Sources: packages/trigger-sdk/CHANGELOG.md56
Cron patterns use the standard 5-field format: minute hour day month weekday
┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
* * * * *
Common patterns:
"0 * * * *" - Every hour"*/15 * * * *" - Every 15 minutes"0 9 * * 1" - Every Monday at 9 AM"0 0 1 * *" - First day of every month at midnightSources: packages/trigger-sdk/package.json57
Scheduled tasks support timezone specification for cron patterns:
Sources: packages/trigger-sdk/package.json57
Scheduled task runs receive a payload containing schedule metadata:
Sources: packages/core/src/v3/schemas/schedules.ts
The server-side triggering process is handled by the TriggerTaskService class, which coordinates between different engine versions.
Sources: apps/webapp/app/v3/services/triggerTask.server.ts1-121
The triggering service processes various concerns when creating a run:
Sources: apps/webapp/app/v3/services/triggerTask.server.ts89-119 apps/webapp/app/runEngine/services/triggerTask.server.ts
The TriggerTaskService class coordinates triggering across engine versions:
Sources: apps/webapp/app/v3/services/triggerTask.server.ts16-77
The schedule engine manages recurring task execution through a worker queue system:
Sources: apps/webapp/app/services/worker.server.ts207-216 apps/webapp/app/v3/scheduleEngine.server.ts
The scheduled task worker is defined in the workerQueue catalog:
This handler processes scheduled task instances with automatic retry logic (up to 3 attempts with 30 seconds total delay).
Sources: apps/webapp/app/services/worker.server.ts207-216
Schedule instances are created when the cron pattern matches the current time, then enqueued as worker jobs. The schedule engine triggers the actual task and tracks the instance status.
Sources: apps/webapp/app/services/worker.server.ts207-216 apps/webapp/app/v3/scheduleEngine.server.ts
When a task is triggered, the run transitions through several states:
| State | Description |
|---|---|
PENDING | Initial state when run is created |
PENDING_VERSION | Waiting for worker deployment version |
DELAYED | Scheduled for future execution (has queueTimestamp) |
QUEUED | Waiting in the run queue for execution |
DEQUEUED | Picked up by a worker, being sent for execution |
EXECUTING | Currently running on a worker |
The transition from PENDING → QUEUED happens when the run is enqueued to the run queue. For delayed runs, the state is DELAYED until the queue timestamp is reached.
Sources: packages/trigger-sdk/CHANGELOG.md252-295 packages/core/CHANGELOG.md260-272
Batch triggers are processed asynchronously through a worker queue system:
Sources: apps/webapp/app/services/worker.server.ts323-341 packages/trigger-sdk/CHANGELOG.md860-884
Batch items can be triggered sequentially or in parallel:
The executionStrategy option controls whether batch items are triggered concurrently or one after another.
Sources: packages/core/CHANGELOG.md341-342 packages/trigger-sdk/CHANGELOG.md813
The batch processing worker tasks are configured with retry logic:
Refresh this wiki
This wiki was recently refreshed. Please wait 1 day to refresh again.