Integrate Trigger.dev into the workflow. Trigger and batch trigger background tasks, retrieve and control runs (cancel, replay, reschedule, tags, metadata, events, traces), manage cron schedules, environment variables, queues, deployments, and waitpoint tokens, and query run data with TRQL.
Trigger a Trigger.dev task by its identifier with an optional JSON payload. Returns the ID of the created run.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
taskIdentifier | string | Yes | Identifier of the task to trigger (e.g., "send-welcome-email") |
payload | json | No | JSON payload passed to the task run. Example: {"userId": "user_123"} |
idempotencyKey | string | No | Idempotency key that ensures the task is only triggered once per key |
queue | string | No | Name of the queue to run the task on |
concurrencyKey | string | No | Key that scopes the queue concurrency limit (e.g., a user ID) |
delay | string | No | Delay before the run executes, as a duration ("30m", "1h", "2d") or an ISO 8601 date |
ttl | string | No | Time-to-live before an unstarted run expires, as a duration ("1h42m") or seconds |
machine | string | No | Machine preset for the run: micro, small-1x, small-2x, medium-1x, medium-2x, large-1x, or large-2x |
tags | string | No | Comma-separated tags to attach to the run (max 10, each under 128 characters) |
| Parameter | Type | Description |
|---|
id | string | ID of the run that was triggered (starts with run_) |
Batch trigger a Trigger.dev task with up to 1,000 payloads. All items in the batch run the same task. Returns the batch ID and the created run IDs.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
taskIdentifier | string | Yes | Identifier of the task to batch trigger (e.g., "send-welcome-email") |
items | json | Yes | JSON array of batch items (max 1,000). Each item is an object with a "payload" and optional "options" (queue, concurrencyKey, idempotencyKey, ttl, delay, tags, machine). Example: [{"payload": {"userId": "user_1"}}, {"payload": {"userId": "user_2"}, "options": {"delay": "1h"}}] |
| Parameter | Type | Description |
|---|
batchId | string | ID of the batch that was triggered |
runIds | array | IDs of the runs created by the batch |
Retrieve a Trigger.dev batch by its ID, including its status, run IDs, and success and failure counts.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
batchId | string | Yes | ID of the batch to retrieve (starts with batch_) |
| Parameter | Type | Description |
|---|
id | string | ID of the batch (starts with batch_) |
status | string | Batch status (PENDING, PROCESSING, COMPLETED, PARTIAL_FAILED, or ABORTED) |
idempotencyKey | string | Idempotency key provided when triggering the batch |
createdAt | string | ISO timestamp when the batch was created |
updatedAt | string | ISO timestamp when the batch was last updated |
runCount | number | Total number of runs in the batch |
runIds | array | IDs of the runs in the batch |
successfulRunCount | number | Number of successful runs, populated after completion |
failedRunCount | number | Number of failed runs, populated after completion |
errors | array | Error details for failed items, present for PARTIAL_FAILED batches |
Retrieve the execution results of every run in a Trigger.dev batch, including outputs and error details.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
batchId | string | Yes | ID of the batch to retrieve results for (starts with batch_) |
| Parameter | Type | Description |
|---|
id | string | ID of the batch (starts with batch_) |
items | array | Execution results for each run in the batch |
Retrieve a Trigger.dev run by its ID, including status, payload, output, attempts, and timing details.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
runId | string | Yes | ID of the run to retrieve (starts with run_) |
| Parameter | Type | Description |
|---|
id | string | Unique ID of the run (starts with run_) |
status | string | Run status (PENDING_VERSION, DELAYED, QUEUED, EXECUTING, REATTEMPTING, FROZEN, COMPLETED, CANCELED, FAILED, CRASHED, INTERRUPTED, or SYSTEM_FAILURE) |
taskIdentifier | string | Identifier of the task the run executes |
version | string | Worker version the run executes on |
idempotencyKey | string | Idempotency key the run was triggered with |
isTest | boolean | Whether the run is a test run |
createdAt | string | ISO timestamp when the run was created |
updatedAt | string | ISO timestamp when the run was last updated |
startedAt | string | ISO timestamp when the run started executing |
finishedAt | string | ISO timestamp when the run finished |
delayedUntil | string | ISO timestamp the run is delayed until |
ttl | string | Time-to-live before an unstarted run expires |
expiredAt | string | ISO timestamp when the run expired |
tags | array | Tags attached to the run |
costInCents | number | Compute cost of the run in cents |
baseCostInCents | number | Base invocation cost of the run in cents |
durationMs | number | Compute duration of the run in milliseconds |
env | object | Environment the run executes in |
metadata | json | Metadata attached to the run |
depth | number | Depth of the run in a parent-child run hierarchy |
batchId | string | ID of the batch the run belongs to, if batch-triggered |
triggerFunction | string | Function used to trigger the run (trigger, triggerAndWait, batchTrigger, or batchTriggerAndWait) |
payload | json | Payload the run was triggered with |
payloadPresignedUrl | string | Presigned URL to download the payload when it is too large to inline |
output | json | Output returned by the run |
outputPresignedUrl | string | Presigned URL to download the output when it is too large to inline |
schedule | object | Schedule that triggered the run, if any |
attempts | array | Attempts made for the run |
relatedRuns | object | Root, parent, and child runs related to this run |
Retrieve the result of a Trigger.dev run: whether it succeeded, its output, and error details. Lighter than Get Run when only the outcome is needed.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
runId | string | Yes | ID of the run to retrieve the result for (starts with run_) |
| Parameter | Type | Description |
|---|
ok | boolean | Whether the run completed successfully |
id | string | ID of the run (starts with run_) |
taskIdentifier | string | Identifier of the task the run executed |
output | json | Output returned by the run, parsed when the output type is JSON |
outputType | string | Content type of the serialized output (e.g., application/json) |
error | json | Error details when the run failed |
durationMs | number | Duration of the run in milliseconds |
Retrieve the log and span events of a Trigger.dev run, including messages, levels, durations, and error events.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
runId | string | Yes | ID of the run to retrieve events for (starts with run_) |
| Parameter | Type | Description |
|---|
events | array | Log and span events recorded during the run |
Retrieve the OpenTelemetry trace of a Trigger.dev run as a tree of spans with timing, errors, and nested children.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
runId | string | Yes | ID of the run to retrieve the trace for (starts with run_) |
| Parameter | Type | Description |
|---|
traceId | string | OpenTelemetry trace ID of the run |
rootSpan | json | Root span of the trace; each span has id, parentId, runId, data (message, taskSlug, startTime, duration, isError, level, events), and recursively nested children spans |
List Trigger.dev runs in the environment of the API key, with optional filters for status, task, version, tags, schedule, and creation time.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
status | string | No | Comma-separated run statuses to filter by: PENDING_VERSION, DELAYED, QUEUED, EXECUTING, REATTEMPTING, FROZEN, COMPLETED, CANCELED, FAILED, CRASHED, INTERRUPTED, SYSTEM_FAILURE |
taskIdentifier | string | No | Comma-separated task identifiers to filter by |
version | string | No | Comma-separated worker versions to filter by (e.g., "20240101.1") |
tag | string | No | Comma-separated tags to filter by |
schedule | string | No | Schedule ID to filter by (starts with sched_) |
isTest | string | No | Filter by test runs: "true" for only test runs, "false" to exclude them |
period | string | No | Only return runs created in the given period (e.g., "1h", "7d") |
from | string | No | Only return runs created on or after this ISO 8601 timestamp |
to | string | No | Only return runs created on or before this ISO 8601 timestamp |
pageSize | number | No | Number of runs per page (max 100, default 25) |
pageAfter | string | No | Run ID to start the page after, for forward pagination |
pageBefore | string | No | Run ID to start the page before, for backward pagination |
| Parameter | Type | Description |
|---|
runs | array | Runs matching the filters |
pagination | object | Cursor pagination details |
Cancel an in-progress Trigger.dev run. Has no effect if the run is already completed.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
runId | string | Yes | ID of the run to cancel (starts with run_) |
| Parameter | Type | Description |
|---|
id | string | ID of the run that was canceled |
Replay a Trigger.dev run, creating a new run with the same payload and options as the original.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
runId | string | Yes | ID of the run to replay (starts with run_) |
| Parameter | Type | Description |
|---|
id | string | ID of the new run created by the replay |
Reschedule a delayed Trigger.dev run with a new delay. Only valid while the run is in the DELAYED state.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
runId | string | Yes | ID of the delayed run to reschedule (starts with run_) |
delay | string | Yes | New delay for the run, as a duration ("30m", "1h", "2d") or an ISO 8601 date to delay until |
| Parameter | Type | Description |
|---|
id | string | Unique ID of the run (starts with run_) |
status | string | Run status (PENDING_VERSION, DELAYED, QUEUED, EXECUTING, REATTEMPTING, FROZEN, COMPLETED, CANCELED, FAILED, CRASHED, INTERRUPTED, or SYSTEM_FAILURE) |
taskIdentifier | string | Identifier of the task the run executes |
version | string | Worker version the run executes on |
idempotencyKey | string | Idempotency key the run was triggered with |
isTest | boolean | Whether the run is a test run |
createdAt | string | ISO timestamp when the run was created |
updatedAt | string | ISO timestamp when the run was last updated |
startedAt | string | ISO timestamp when the run started executing |
finishedAt | string | ISO timestamp when the run finished |
delayedUntil | string | ISO timestamp the run is delayed until |
ttl | string | Time-to-live before an unstarted run expires |
expiredAt | string | ISO timestamp when the run expired |
tags | array | Tags attached to the run |
costInCents | number | Compute cost of the run in cents |
baseCostInCents | number | Base invocation cost of the run in cents |
durationMs | number | Compute duration of the run in milliseconds |
env | object | Environment the run executes in |
metadata | json | Metadata attached to the run |
depth | number | Depth of the run in a parent-child run hierarchy |
batchId | string | ID of the batch the run belongs to, if batch-triggered |
triggerFunction | string | Function used to trigger the run (trigger, triggerAndWait, batchTrigger, or batchTriggerAndWait) |
payload | json | Payload the run was triggered with |
payloadPresignedUrl | string | Presigned URL to download the payload when it is too large to inline |
output | json | Output returned by the run |
outputPresignedUrl | string | Presigned URL to download the output when it is too large to inline |
schedule | object | Schedule that triggered the run, if any |
attempts | array | Attempts made for the run |
relatedRuns | object | Root, parent, and child runs related to this run |
Add tags to an existing Trigger.dev run. Runs can have up to 10 tags.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
runId | string | Yes | ID of the run to tag (starts with run_) |
tags | string | Yes | Comma-separated tags to add to the run (max 10 total, each under 128 characters) |
| Parameter | Type | Description |
|---|
message | string | Confirmation message for the added tags |
Replace the metadata of a Trigger.dev run with a new JSON object.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
runId | string | Yes | ID of the run to update (starts with run_) |
metadata | json | Yes | JSON object to set as the run metadata. Example: {"stage": "approved"} |
| Parameter | Type | Description |
|---|
metadata | json | The updated metadata of the run |
Create an imperative cron schedule that triggers a Trigger.dev task on a recurring basis.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
task | string | Yes | Identifier of the task to schedule (e.g., "daily-report") |
cron | string | Yes | Cron expression defining when the task runs (e.g., "0 0 * * *") |
timezone | string | No | IANA timezone the cron expression is evaluated in (e.g., "America/New_York"). Defaults to UTC |
externalId | string | No | External identifier to associate with the schedule (e.g., a user ID) |
deduplicationKey | string | Yes | Key that prevents duplicate schedules; creating again with the same key updates the existing schedule |
| Parameter | Type | Description |
|---|
id | string | Unique ID of the schedule (starts with sched_) |
task | string | Identifier of the task the schedule triggers |
type | string | Schedule type (DECLARATIVE or IMPERATIVE) |
active | boolean | Whether the schedule is active |
deduplicationKey | string | Deduplication key of the schedule |
externalId | string | External ID associated with the schedule |
cron | string | Cron expression of the schedule |
cronDescription | string | Human-readable description of the cron expression |
timezone | string | IANA timezone of the schedule |
nextRun | string | ISO timestamp of the next scheduled run |
environments | array | Environments the schedule runs in |
Retrieve a Trigger.dev schedule by its ID.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
scheduleId | string | Yes | ID of the schedule to retrieve (starts with sched_) |
| Parameter | Type | Description |
|---|
id | string | Unique ID of the schedule (starts with sched_) |
task | string | Identifier of the task the schedule triggers |
type | string | Schedule type (DECLARATIVE or IMPERATIVE) |
active | boolean | Whether the schedule is active |
deduplicationKey | string | Deduplication key of the schedule |
externalId | string | External ID associated with the schedule |
cron | string | Cron expression of the schedule |
cronDescription | string | Human-readable description of the cron expression |
timezone | string | IANA timezone of the schedule |
nextRun | string | ISO timestamp of the next scheduled run |
environments | array | Environments the schedule runs in |
List Trigger.dev schedules in the project, with page-based pagination.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
page | number | No | Page number to return (default 1) |
perPage | number | No | Number of schedules per page |
| Parameter | Type | Description |
|---|
schedules | array | Schedules in the project |
pagination | object | Page-based pagination details |
Update an imperative Trigger.dev schedule by its ID, replacing its task, cron expression, timezone, and external ID.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
scheduleId | string | Yes | ID of the schedule to update (starts with sched_) |
task | string | Yes | Identifier of the task the schedule triggers (e.g., "daily-report") |
cron | string | Yes | Cron expression defining when the task runs (e.g., "0 0 * * *") |
timezone | string | No | IANA timezone the cron expression is evaluated in (e.g., "America/New_York"). Defaults to UTC |
externalId | string | No | External identifier to associate with the schedule (e.g., a user ID) |
| Parameter | Type | Description |
|---|
id | string | Unique ID of the schedule (starts with sched_) |
task | string | Identifier of the task the schedule triggers |
type | string | Schedule type (DECLARATIVE or IMPERATIVE) |
active | boolean | Whether the schedule is active |
deduplicationKey | string | Deduplication key of the schedule |
externalId | string | External ID associated with the schedule |
cron | string | Cron expression of the schedule |
cronDescription | string | Human-readable description of the cron expression |
timezone | string | IANA timezone of the schedule |
nextRun | string | ISO timestamp of the next scheduled run |
environments | array | Environments the schedule runs in |
Delete an imperative Trigger.dev schedule by its ID.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
scheduleId | string | Yes | ID of the schedule to delete (starts with sched_) |
| Parameter | Type | Description |
|---|
deleted | boolean | Whether the schedule was deleted |
scheduleId | string | ID of the schedule that was deleted |
Activate an imperative Trigger.dev schedule so it resumes triggering its task.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
scheduleId | string | Yes | ID of the schedule to activate (starts with sched_) |
| Parameter | Type | Description |
|---|
id | string | Unique ID of the schedule (starts with sched_) |
task | string | Identifier of the task the schedule triggers |
type | string | Schedule type (DECLARATIVE or IMPERATIVE) |
active | boolean | Whether the schedule is active |
deduplicationKey | string | Deduplication key of the schedule |
externalId | string | External ID associated with the schedule |
cron | string | Cron expression of the schedule |
cronDescription | string | Human-readable description of the cron expression |
timezone | string | IANA timezone of the schedule |
nextRun | string | ISO timestamp of the next scheduled run |
environments | array | Environments the schedule runs in |
Deactivate an imperative Trigger.dev schedule so it stops triggering its task.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
scheduleId | string | Yes | ID of the schedule to deactivate (starts with sched_) |
| Parameter | Type | Description |
|---|
id | string | Unique ID of the schedule (starts with sched_) |
task | string | Identifier of the task the schedule triggers |
type | string | Schedule type (DECLARATIVE or IMPERATIVE) |
active | boolean | Whether the schedule is active |
deduplicationKey | string | Deduplication key of the schedule |
externalId | string | External ID associated with the schedule |
cron | string | Cron expression of the schedule |
cronDescription | string | Human-readable description of the cron expression |
timezone | string | IANA timezone of the schedule |
nextRun | string | ISO timestamp of the next scheduled run |
environments | array | Environments the schedule runs in |
List the environment variables of a Trigger.dev project environment. Values are returned in plaintext and will appear in workflow outputs and run history — scope this operation carefully.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
projectRef | string | Yes | External ref of the project, from the project settings (starts with proj_) |
environment | string | Yes | Environment to list variables for: dev, staging, or prod |
| Parameter | Type | Description |
|---|
variables | array | Environment variables in the project environment |
Create an environment variable in a Trigger.dev project environment.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
projectRef | string | Yes | External ref of the project, from the project settings (starts with proj_) |
environment | string | Yes | Environment to create the variable in: dev, staging, or prod |
name | string | Yes | Name of the environment variable (e.g., "SLACK_API_KEY") |
value | string | Yes | Value of the environment variable |
| Parameter | Type | Description |
|---|
success | boolean | Whether the environment variable was created |
name | string | Name of the environment variable that was created |
Retrieve an environment variable from a Trigger.dev project environment. The value is returned in plaintext and will appear in workflow outputs and run history.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
projectRef | string | Yes | External ref of the project, from the project settings (starts with proj_) |
environment | string | Yes | Environment to read the variable from: dev, staging, or prod |
name | string | Yes | Name of the environment variable (e.g., "SLACK_API_KEY") |
| Parameter | Type | Description |
|---|
name | string | Name of the environment variable |
value | string | Plaintext value of the environment variable; appears in workflow outputs and run history |
Update the value of an environment variable in a Trigger.dev project environment.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
projectRef | string | Yes | External ref of the project, from the project settings (starts with proj_) |
environment | string | Yes | Environment the variable belongs to: dev, staging, or prod |
name | string | Yes | Name of the environment variable to update (e.g., "SLACK_API_KEY") |
value | string | Yes | New value of the environment variable |
| Parameter | Type | Description |
|---|
success | boolean | Whether the environment variable was updated |
name | string | Name of the environment variable that was updated |
Delete an environment variable from a Trigger.dev project environment.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
projectRef | string | Yes | External ref of the project, from the project settings (starts with proj_) |
environment | string | Yes | Environment the variable belongs to: dev, staging, or prod |
name | string | Yes | Name of the environment variable to delete (e.g., "SLACK_API_KEY") |
| Parameter | Type | Description |
|---|
success | boolean | Whether the environment variable was deleted |
name | string | Name of the environment variable that was deleted |
Upload multiple environment variables to a Trigger.dev project environment in one request.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
projectRef | string | Yes | External ref of the project, from the project settings (starts with proj_) |
environment | string | Yes | Environment to upload the variables to: dev, staging, or prod |
variables | json | Yes | JSON array of environment variables to upload. Example: [{"name": "SLACK_API_KEY", "value": "slack_123"}] |
override | string | No | Whether to override existing variables: "true" or "false" (default false) |
| Parameter | Type | Description |
|---|
success | boolean | Whether the environment variables were uploaded |
count | number | Number of environment variables submitted |
Retrieve a Trigger.dev queue by ID, task identifier, or custom queue name, including its running and queued counts.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
queueName | string | Yes | Queue ID (starts with queue_), task identifier, or custom queue name, depending on the queue type |
queueType | string | No | How to interpret the queue name: "id" (default) for a queue ID, "task" for a task identifier, or "custom" for a custom queue name |
| Parameter | Type | Description |
|---|
id | string | Unique ID of the queue (starts with queue_) |
name | string | Name of the queue |
type | string | Queue type (task for task-default queues, custom for named queues) |
running | number | Number of runs currently executing |
queued | number | Number of runs waiting in the queue |
paused | boolean | Whether the queue is paused |
concurrencyLimit | number | Maximum number of runs that can execute concurrently |
concurrency | object | Concurrency details for the queue |
List the queues in the environment of the API key, including running and queued counts, with page-based pagination.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
page | number | No | Page number to return (default 1) |
perPage | number | No | Number of queues per page |
| Parameter | Type | Description |
|---|
queues | array | Queues in the environment |
pagination | object | Page-based pagination details |
Pause a Trigger.dev queue so no new runs start. Runs that are currently executing continue to completion.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
queueName | string | Yes | Queue ID (starts with queue_), task identifier, or custom queue name, depending on the queue type |
queueType | string | No | How to interpret the queue name: "id" (default) for a queue ID, "task" for a task identifier, or "custom" for a custom queue name |
| Parameter | Type | Description |
|---|
id | string | Unique ID of the queue (starts with queue_) |
name | string | Name of the queue |
type | string | Queue type (task for task-default queues, custom for named queues) |
running | number | Number of runs currently executing |
queued | number | Number of runs waiting in the queue |
paused | boolean | Whether the queue is paused |
concurrencyLimit | number | Maximum number of runs that can execute concurrently |
concurrency | object | Concurrency details for the queue |
Resume a paused Trigger.dev queue so new runs can start again.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
queueName | string | Yes | Queue ID (starts with queue_), task identifier, or custom queue name, depending on the queue type |
queueType | string | No | How to interpret the queue name: "id" (default) for a queue ID, "task" for a task identifier, or "custom" for a custom queue name |
| Parameter | Type | Description |
|---|
id | string | Unique ID of the queue (starts with queue_) |
name | string | Name of the queue |
type | string | Queue type (task for task-default queues, custom for named queues) |
running | number | Number of runs currently executing |
queued | number | Number of runs waiting in the queue |
paused | boolean | Whether the queue is paused |
concurrencyLimit | number | Maximum number of runs that can execute concurrently |
concurrency | object | Concurrency details for the queue |
Override the concurrency limit of a Trigger.dev queue with a new value.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
queueName | string | Yes | Queue ID (starts with queue_), task identifier, or custom queue name, depending on the queue type |
queueType | string | No | How to interpret the queue name: "id" (default) for a queue ID, "task" for a task identifier, or "custom" for a custom queue name |
concurrencyLimit | number | Yes | New concurrency limit for the queue (0 to 100000) |
| Parameter | Type | Description |
|---|
id | string | Unique ID of the queue (starts with queue_) |
name | string | Name of the queue |
type | string | Queue type (task for task-default queues, custom for named queues) |
running | number | Number of runs currently executing |
queued | number | Number of runs waiting in the queue |
paused | boolean | Whether the queue is paused |
concurrencyLimit | number | Maximum number of runs that can execute concurrently |
concurrency | object | Concurrency details for the queue |
Reset the concurrency limit of a Trigger.dev queue back to its base value, removing any override.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
queueName | string | Yes | Queue ID (starts with queue_), task identifier, or custom queue name, depending on the queue type |
queueType | string | No | How to interpret the queue name: "id" (default) for a queue ID, "task" for a task identifier, or "custom" for a custom queue name |
| Parameter | Type | Description |
|---|
id | string | Unique ID of the queue (starts with queue_) |
name | string | Name of the queue |
type | string | Queue type (task for task-default queues, custom for named queues) |
running | number | Number of runs currently executing |
queued | number | Number of runs waiting in the queue |
paused | boolean | Whether the queue is paused |
concurrencyLimit | number | Maximum number of runs that can execute concurrently |
concurrency | object | Concurrency details for the queue |
List Trigger.dev deployments in the environment of the API key, with optional status and creation-time filters.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
status | string | No | Deployment status to filter by: PENDING, BUILDING, DEPLOYING, DEPLOYED, FAILED, CANCELED, or TIMED_OUT |
period | string | No | Only return deployments created in the given period (e.g., "1h", "7d") |
from | string | No | Only return deployments created on or after this ISO 8601 timestamp |
to | string | No | Only return deployments created on or before this ISO 8601 timestamp |
pageSize | number | No | Number of deployments per page (5 to 100, default 20) |
pageAfter | string | No | Cursor to start the page after, from the previous response pagination |
| Parameter | Type | Description |
|---|
deployments | array | Deployments matching the filters |
pagination | object | Cursor pagination details |
Retrieve a Trigger.dev deployment by its ID, including its status, version, and registered tasks.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
deploymentId | string | Yes | ID of the deployment to retrieve |
| Parameter | Type | Description |
|---|
id | string | Unique ID of the deployment |
status | string | Deployment status (PENDING, INSTALLING, BUILDING, DEPLOYING, DEPLOYED, FAILED, CANCELED, or TIMED_OUT) |
version | string | Deployment version (e.g., "20250228.1") |
shortCode | string | Short code of the deployment |
createdAt | string | ISO timestamp when the deployment was created |
deployedAt | string | ISO timestamp when the deployment was promoted to DEPLOYED |
runtime | string | Runtime used by the deployment (e.g., "node") |
runtimeVersion | string | Runtime version of the deployment |
git | json | Git metadata associated with the deployment |
error | json | Error details when the deployment failed |
tasks | array | Tasks registered by the deployed worker |
Retrieve the latest Trigger.dev deployment in the environment of the API key.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
| Parameter | Type | Description |
|---|
id | string | Unique ID of the deployment |
status | string | Deployment status (PENDING, INSTALLING, BUILDING, DEPLOYING, DEPLOYED, FAILED, CANCELED, or TIMED_OUT) |
version | string | Deployment version (e.g., "20250228.1") |
shortCode | string | Short code of the deployment |
createdAt | string | ISO timestamp when the deployment was created |
deployedAt | string | ISO timestamp when the deployment was promoted to DEPLOYED |
runtime | string | Runtime used by the deployment (e.g., "node") |
runtimeVersion | string | Runtime version of the deployment |
git | json | Git metadata associated with the deployment |
error | json | Error details when the deployment failed |
tasks | array | Tasks registered by the deployed worker |
Promote a Trigger.dev deployment version so new runs execute on it (e.g., to roll back to a previous version).
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
version | string | Yes | Deployment version to promote (e.g., "20250228.1") |
| Parameter | Type | Description |
|---|
id | string | ID of the promoted deployment |
version | string | Version of the promoted deployment |
shortCode | string | Short code of the promoted deployment |
Execute a TRQL (SQL-like) query against Trigger.dev run data for reporting and analytics.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
query | string | Yes | TRQL query to execute (e.g., "SELECT run_id, status, triggered_at FROM runs WHERE status = 'Failed' LIMIT 10") |
scope | string | No | Scope of data to query: environment (default), project, or organization |
period | string | No | Time period shorthand (e.g., "1h", "7d", "30d"). Cannot be combined with from/to |
from | string | No | Start of the time range as an ISO 8601 timestamp. Must be used with "to" |
to | string | No | End of the time range as an ISO 8601 timestamp. Must be used with "from" |
format | string | No | Response format: "json" (default) for structured rows or "csv" for a CSV string |
| Parameter | Type | Description |
|---|
format | string | Format of the results (json or csv) |
results | json | Query results: an array of row objects for json format, a CSV string for csv |
Retrieve the TRQL query schema: the tables and columns available for Execute Query, with types and allowed values.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
| Parameter | Type | Description |
|---|
tables | array | Tables that can be queried with TRQL |
Create a Trigger.dev waitpoint token that a task can wait on until it is completed from outside (e.g., a human approval).
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
timeout | string | No | How long before the token times out, as a duration ("30s", "1m", "2h", "3d") or an ISO 8601 date |
idempotencyKey | string | No | Idempotency key; passing the same key before it expires returns the original token |
idempotencyKeyTTL | string | No | How long the idempotency key is valid, as a duration ("30s", "1m", "2h", "3d") |
tags | string | No | Comma-separated tags to attach to the waitpoint (max 10, each under 128 characters) |
| Parameter | Type | Description |
|---|
id | string | Unique ID of the waitpoint token (starts with waitpoint_) |
isCached | boolean | Whether an existing token was returned because the same idempotency key was reused |
url | string | HTTP callback URL; a POST request to this URL completes the waitpoint without an API key |
Complete a Trigger.dev waitpoint token, resuming any task waiting on it and passing it optional JSON data.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
waitpointId | string | Yes | ID of the waitpoint token to complete (starts with waitpoint_) |
data | json | No | JSON data passed back to the waiting run as the token result. Example: {"status": "approved"} |
| Parameter | Type | Description |
|---|
success | boolean | Whether the waitpoint token was completed |
Retrieve a Trigger.dev waitpoint token by its ID, including its status, timeout, and completion data.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
waitpointId | string | Yes | ID of the waitpoint token to retrieve (starts with waitpoint_) |
| Parameter | Type | Description |
|---|
id | string | Unique ID of the waitpoint token (starts with waitpoint_) |
url | string | HTTP callback URL; a POST request to this URL completes the waitpoint without an API key |
status | string | Status of the waitpoint token (WAITING, COMPLETED, or TIMED_OUT) |
idempotencyKey | string | Idempotency key used when creating the token |
idempotencyKeyExpiresAt | string | ISO timestamp when the idempotency key expires |
timeoutAt | string | ISO timestamp when the token times out |
completedAt | string | ISO timestamp when the token was completed |
output | json | Data passed when completing the token, parsed when the output type is JSON |
outputType | string | Content type of the serialized output (e.g., application/json) |
outputIsError | boolean | Whether the output represents an error (e.g., a timeout) |
tags | array | Tags attached to the waitpoint |
createdAt | string | ISO timestamp when the token was created |
List Trigger.dev waitpoint tokens in the environment of the API key, with optional status, tag, and creation-time filters.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
status | string | No | Waitpoint status to filter by: WAITING, COMPLETED, or TIMED_OUT |
idempotencyKey | string | No | Idempotency key to filter by |
tags | string | No | Comma-separated tags to filter by |
period | string | No | Only return tokens created in the given period (e.g., "1h", "7d") |
from | string | No | Only return tokens created on or after this ISO 8601 timestamp |
to | string | No | Only return tokens created on or before this ISO 8601 timestamp |
pageSize | number | No | Number of tokens per page (max 100) |
pageAfter | string | No | Waitpoint ID to start the page after, for forward pagination |
pageBefore | string | No | Waitpoint ID to start the page before, for backward pagination |
| Parameter | Type | Description |
|---|
tokens | array | Waitpoint tokens matching the filters |
pagination | object | Cursor pagination details |
List the IANA timezones supported by Trigger.dev schedules, for use as the timezone of a cron schedule.
| Parameter | Type | Required | Description |
|---|
apiKey | string | Yes | Trigger.dev secret API key (starts with tr_) |
excludeUtc | string | No | Set to "true" to exclude UTC from the returned timezones |
| Parameter | Type | Description |
|---|
timezones | array | IANA timezones supported by schedules |
- Category:
tools
- Type:
trigger_dev
