Trigger.dev

App · 26 actions

Run and manage your Trigger.dev background tasks: trigger a task or a batch of runs, find, replay, cancel and tag runs, manage schedules, environment variables and queues, and start a workflow when a run starts, completes, fails or changes status.

Actions

ActionWhat it does
Add tags to runAdd tags to a run, to find it by later.
Cancel runCancel a run that is waiting or running.
Change delayed run's start timeMove the start time of a run that is waiting for one (status DELAYED), such as one triggered with a start time.
Create environment variableAdd an environment variable for your tasks.
Create scheduleRun a scheduled task on a cron schedule, in a time zone of your choice.
Delete environment variableDelete an environment variable from the API key's environment.
Delete scheduleDelete a schedule made in the dashboard or with 'Create schedule'.
Get batchGet a batch of runs: its status, the ids of its runs, and how many started or failed to start.
Get environment variableGet one environment variable's value.
Get queueGet one queue with how many runs it has waiting and running, its limit, and whether it is paused.
Get runGet one run with its status, payload, output or error, each attempt, and the runs it is linked to.
Get scheduleGet one schedule with its task, cron, time zone, whether it is on and when it next runs.
Import environment variablesAdd several environment variables at once from names and values, optionally replacing ones that already exist.
List deploymentsList the environment's deployments, newest first, with their version and status, optionally only those in one status or time range.
List environment variablesList the environment variables your tasks get in the API key's environment.
List queuesList the environment's queues with how many runs each has waiting and running, its limit, and whether it is paused.
List runsList runs, newest first, filtered by status, task, when they were created, tag, schedule or version.
List schedulesList the environment's schedules with their task, cron, time zone, whether each is on and when it next runs.
Pause or resume queuePause a queue, so no new runs start from it (runs already going finish), or set it running again.
Replay runStart a new run of the same task with the same payload and options as an earlier run, optionally with a different payload, start time or tags.
Set run metadataReplace a run's metadata (its own keys and values, which the task can read and show in the dashboard) with the keys and values given.
Trigger taskStart a run of one of your tasks with a payload, now or at a set time, in the environment the API key belongs to.
Trigger task for each itemStart one run of a task for each payload in a list (up to 1,000), in one request.
Turn schedule on or offTurn a schedule on (active) or off (inactive).
Update environment variableChange the value of an environment variable that already exists.
Update scheduleChange a schedule's task, cron, time zone or your own ID.

Add tags to run

Add tags to a run, to find it by later. A run holds at most 10; tags it already has are ignored.

Inputs

Run IDrun_idtextRequired
The run's id, which starts with run_, from 'Trigger task', 'List runs' or a trigger.
TagstagslistRequired
The tags to add, such as user_123.

Outputs

messagetext
What Trigger.dev said
run_idtext
The run's id
tags_addedlist
The tags sent
Example output
{
  "message": "Successfully set 1 new tags.",
  "run_id": "run_cm4w9x0r20001n2m3a4b5c6d",
  "tags_added": [
    "user_123"
  ]
}

Cancel run

Cancel a run that is waiting or running. A run that has already finished is left as it is.

Inputs

Run IDrun_idtextRequired
The run's id, which starts with run_, from 'Trigger task', 'List runs' or a trigger.

Outputs

cancel_requestedtrue/false
Always true; 'Get run' shows CANCELED once it has stopped
run_idtext
The run's id
Example output
{
  "cancel_requested": true,
  "run_id": "run_cm4w9x0r20001n2m3a4b5c6d"
}

Change delayed run's start time

Move the start time of a run that is waiting for one (status DELAYED), such as one triggered with a start time.

Inputs

Run IDrun_idtextRequired
The run's id, which starts with run_, from 'Trigger task', 'List runs' or a trigger.
New start timestart_atdate and timeRequired
When the run should start instead.

Outputs

runobject
The run
Example output
{
  "run": {
    "attemptCount": 1,
    "attempts": [
      {
        "completedAt": "2026-10-15T09:00:04.200Z",
        "createdAt": "2026-10-15T09:00:00.000Z",
        "error": {
          "message": "Email address is not valid",
          "name": "Error",
          "stackTrace": "Error: ..."
        },
        "id": "attempt_1234",
        "startedAt": "2026-10-15T09:00:00.000Z",
        "status": "COMPLETED",
        "updatedAt": "2026-10-15T09:00:04.200Z"
      }
    ],
    "baseCostInCents": 0.0,
    "batchId": "",
    "costInCents": 0.05,
    "createdAt": "2026-10-15T09:00:00.000Z",
    "delayedUntil": "",
    "depth": 0,
    "durationMs": 3200,
    "error": {
      "message": "Email address is not valid",
      "name": "Error",
      "stackTrace": "Error: ..."
    },
    "expiredAt": "",
    "finishedAt": "2026-10-15T09:00:04.200Z",
    "id": "run_cm4w9x0r20001n2m3a4b5c6d",
    "idempotencyKey": "",
    "isCancelled": false,
    "isCompleted": true,
    "isExecuting": false,
    "isFailed": false,
    "isQueued": false,
    "isSuccess": true,
    "isTest": false,
    "isWaiting": false,
    "metadata": {},
    "output": {
      "sent": true
    },
    "outputPresignedUrl": "",
    "payload": {
      "email": "jo@example.com"
    },
    "payloadPresignedUrl": "",
    "relatedRuns": {
      "children": [],
      "parent": {},
      "root": {}
    },
    "schedule": {
      "deduplicationKey": "weekly",
      "externalId": "",
      "generator": {
        "description": "At 09:00 AM, only on Monday",
        "expression": "0 9 * * 1",
        "type": "CRON"
      },
      "id": "sched_1234abcd"
    },
    "startedAt": "2026-10-15T09:00:01Z",
    "status": "COMPLETED",
    "tags": [
      "user_123"
    ],
    "taskIdentifier": "send-welcome-email",
    "triggerFunction": "trigger",
    "ttl": "",
    "updatedAt": "2026-10-15T09:00:04.200Z",
    "version": "20261015.1"
  }
}

Create environment variable

Add an environment variable for your tasks. One of the same name is overwritten. Tasks get it from their next run.

Inputs

NamenametextRequired
The variable's name: letters, digits and underscores, such as DATABASE_URL.
ValuevaluetextRequired
The variable's value.

Outputs

createdtrue/false
Always true once created
environmenttext
The environment, read from the API key, such as prod
nametext
The variable's name
Example output
{
  "created": true,
  "environment": "prod",
  "name": "DATABASE_URL"
}

Create schedule

Run a scheduled task on a cron schedule, in a time zone of your choice. Creating the same schedule again changes it rather than making a copy.

Inputs

TasktasktextRequired
The scheduled task to run (one written with schedules.task). Pick one, or type its id.
CroncrontextRequired
When to run, as five parts: minute, hour, day of month, month, day of week. 0 9 * * 1 is 9:00 every Monday; */15 * * * * is every 15 minutes.
Time zonetimezonetext
The time zone the times in the cron are in. Defaults to UTC.
Your own IDexternal_idtext
Any id that means something to you, such as a customer's id. The task receives it on every run.
Deduplication keydeduplication_keytext
Text that names this schedule, so creating it again changes it instead of making a copy. Leave empty to make one from the task, cron, time zone and your ID.

Outputs

scheduleobject
The schedule
Example output
{
  "schedule": {
    "active": true,
    "deduplicationKey": "weekly",
    "environments": [
      {
        "id": "env_1234",
        "type": "PRODUCTION",
        "userName": ""
      }
    ],
    "externalId": "user_123",
    "generator": {
      "description": "At 09:00 AM, only on Monday",
      "expression": "0 9 * * 1",
      "type": "CRON"
    },
    "id": "sched_1234abcd",
    "nextRun": "2026-10-19T13:00:00.000Z",
    "task": "send-welcome-email",
    "timezone": "America/New_York",
    "type": "IMPERATIVE"
  }
}

Delete environment variable

Delete an environment variable from the API key's environment.

Inputs

VariablenametextRequired
The variable's name. Pick one, or type it, such as DATABASE_URL.

Outputs

deletedtrue/false
Always true once deleted
environmenttext
The environment, read from the API key, such as prod
nametext
The variable's name
Example output
{
  "deleted": true,
  "environment": "prod",
  "name": "DATABASE_URL"
}

Delete schedule

Delete a schedule made in the dashboard or with 'Create schedule'. Schedules written in code can only be removed in code.

Inputs

Scheduleschedule_idtextRequired
The schedule. Pick one, or give its id (it starts with sched_).

Outputs

deletedtrue/false
Always true once deleted
schedule_idtext
The schedule deleted
Example output
{
  "deleted": true,
  "schedule_id": "sched_1234abcd"
}

Get batch

Get a batch of runs: its status, the ids of its runs, and how many started or failed to start.

Inputs

Batch IDbatch_idtextRequired
The batch's id, which starts with batch_, from 'Trigger task for each item'.

Outputs

batchobject
The batch
Example output
{
  "batch": {
    "createdAt": "2026-10-15T09:00:00.000Z",
    "errors": [],
    "failedRunCount": 0,
    "id": "batch_1234abcd",
    "idempotencyKey": "",
    "runCount": 1,
    "runs": [
      "run_cm4w9x0r20001n2m3a4b5c6d"
    ],
    "status": "COMPLETED",
    "successfulRunCount": 1,
    "updatedAt": "2026-10-15T09:00:04.200Z"
  }
}

Get environment variable

Get one environment variable's value.

Inputs

VariablenametextRequired
The variable's name. Pick one, or type it, such as DATABASE_URL.

Outputs

environmenttext
The environment, read from the API key, such as prod
nametext
The variable's name
valuetext
Its value
Example output
{
  "environment": "prod",
  "name": "DATABASE_URL",
  "value": "postgres://..."
}

Get queue

Get one queue with how many runs it has waiting and running, its limit, and whether it is paused.

Inputs

Queuequeue_idtextRequired
The queue. Pick one, or give its id (it starts with queue_).

Outputs

queueobject
The queue
Example output
{
  "queue": {
    "concurrency": {
      "base": 10,
      "current": 10,
      "overriddenAt": "",
      "overriddenBy": "",
      "override": 0
    },
    "concurrencyLimit": 10,
    "id": "queue_1234abcd",
    "name": "send-welcome-email",
    "paused": false,
    "queued": 0,
    "running": 0,
    "type": "task",
    "version": "V2"
  }
}

Get run

Get one run with its status, payload, output or error, each attempt, and the runs it is linked to.

Inputs

Run IDrun_idtextRequired
The run's id, which starts with run_, from 'Trigger task', 'List runs' or a trigger.

Outputs

runobject
The run
Example output
{
  "run": {
    "attemptCount": 1,
    "attempts": [
      {
        "completedAt": "2026-10-15T09:00:04.200Z",
        "createdAt": "2026-10-15T09:00:00.000Z",
        "error": {
          "message": "Email address is not valid",
          "name": "Error",
          "stackTrace": "Error: ..."
        },
        "id": "attempt_1234",
        "startedAt": "2026-10-15T09:00:00.000Z",
        "status": "COMPLETED",
        "updatedAt": "2026-10-15T09:00:04.200Z"
      }
    ],
    "baseCostInCents": 0.0,
    "batchId": "",
    "costInCents": 0.05,
    "createdAt": "2026-10-15T09:00:00.000Z",
    "delayedUntil": "",
    "depth": 0,
    "durationMs": 3200,
    "error": {
      "message": "Email address is not valid",
      "name": "Error",
      "stackTrace": "Error: ..."
    },
    "expiredAt": "",
    "finishedAt": "2026-10-15T09:00:04.200Z",
    "id": "run_cm4w9x0r20001n2m3a4b5c6d",
    "idempotencyKey": "",
    "isCancelled": false,
    "isCompleted": true,
    "isExecuting": false,
    "isFailed": false,
    "isQueued": false,
    "isSuccess": true,
    "isTest": false,
    "isWaiting": false,
    "metadata": {},
    "output": {
      "sent": true
    },
    "outputPresignedUrl": "",
    "payload": {
      "email": "jo@example.com"
    },
    "payloadPresignedUrl": "",
    "relatedRuns": {
      "children": [],
      "parent": {},
      "root": {}
    },
    "schedule": {
      "deduplicationKey": "weekly",
      "externalId": "",
      "generator": {
        "description": "At 09:00 AM, only on Monday",
        "expression": "0 9 * * 1",
        "type": "CRON"
      },
      "id": "sched_1234abcd"
    },
    "startedAt": "2026-10-15T09:00:01Z",
    "status": "COMPLETED",
    "tags": [
      "user_123"
    ],
    "taskIdentifier": "send-welcome-email",
    "triggerFunction": "trigger",
    "ttl": "",
    "updatedAt": "2026-10-15T09:00:04.200Z",
    "version": "20261015.1"
  }
}

Get schedule

Get one schedule with its task, cron, time zone, whether it is on and when it next runs.

Inputs

Scheduleschedule_idtextRequired
The schedule. Pick one, or give its id (it starts with sched_).

Outputs

scheduleobject
The schedule
Example output
{
  "schedule": {
    "active": true,
    "deduplicationKey": "weekly",
    "environments": [
      {
        "id": "env_1234",
        "type": "PRODUCTION",
        "userName": ""
      }
    ],
    "externalId": "user_123",
    "generator": {
      "description": "At 09:00 AM, only on Monday",
      "expression": "0 9 * * 1",
      "type": "CRON"
    },
    "id": "sched_1234abcd",
    "nextRun": "2026-10-19T13:00:00.000Z",
    "task": "send-welcome-email",
    "timezone": "America/New_York",
    "type": "IMPERATIVE"
  }
}

Import environment variables

Add several environment variables at once from names and values, optionally replacing ones that already exist.

Inputs

VariablesvariablesobjectRequired
Each variable's name with its value, such as {"API_URL": "https://..."}.
Replace existingoverridetrue/false
On replaces variables that already exist; off leaves them as they are.

Outputs

countnumber
How many were sent
environmenttext
The environment, read from the API key, such as prod
nameslist
The names sent
replaced_existingtrue/false
Whether variables already there were replaced
Example output
{
  "count": 1,
  "environment": "prod",
  "names": [
    "API_URL"
  ],
  "replaced_existing": false
}

List deployments

List the environment's deployments, newest first, with their version and status, optionally only those in one status or time range.

Inputs

Statusstatustext
Only deployments in this status.One of: DEPLOYED, FAILED, PENDING, BUILDING, DEPLOYING, CANCELED, TIMED_OUT (Timed out).
Created aftercreated_afterdate and time
Only deployments started at or after this time.
Created beforecreated_beforedate and time
Only deployments started at or before this time. Needs 'Created after' too.
Page sizelimitnumber
How many to return, 5 to 100. Trigger.dev's default is 20.From 5 to 100.
Next page cursoraftertext
The 'next_cursor' from an earlier page of deployments, for the next one.

Outputs

countnumber
How many came back
deploymentslist
The deployments
next_cursortext
Pass as 'Next page cursor' for the next page; empty on the last
Example output
{
  "count": 1,
  "deployments": [
    {
      "createdAt": "2026-10-15T09:00:00.000Z",
      "deployedAt": "2026-10-15T09:00:04.200Z",
      "error": {},
      "externalId": "",
      "git": {},
      "id": "deployment_1234",
      "runtime": "node",
      "runtimeVersion": "22.12.0",
      "shortCode": "abc123",
      "status": "DEPLOYED",
      "version": "20261015.1"
    }
  ],
  "next_cursor": ""
}

List environment variables

List the environment variables your tasks get in the API key's environment. Secret variables' values come back hidden.

Inputs

None.

Outputs

countnumber
How many came back
environmenttext
The environment, read from the API key, such as prod
variableslist
The variables
Example output
{
  "count": 1,
  "environment": "prod",
  "variables": [
    {
      "name": "DATABASE_URL",
      "value": "postgres://..."
    }
  ]
}

List queues

List the environment's queues with how many runs each has waiting and running, its limit, and whether it is paused.

Inputs

Pagepagenumber
Which page to return, starting at 1.At least 1.
Page sizeper_pagenumber
How many to return on each page, 1 to 100.From 1 to 100.

Outputs

countnumber
How many came back
pagenumber
Which page this is
queueslist
The queues
totalnumber
How many there are in all
total_pagesnumber
How many pages there are
Example output
{
  "count": 1,
  "page": 1,
  "queues": [
    {
      "concurrency": {
        "base": 10,
        "current": 10,
        "overriddenAt": "",
        "overriddenBy": "",
        "override": 0
      },
      "concurrencyLimit": 10,
      "id": "queue_1234abcd",
      "name": "send-welcome-email",
      "paused": false,
      "queued": 0,
      "running": 0,
      "type": "task",
      "version": "V2"
    }
  ],
  "total": 1,
  "total_pages": 1
}

List runs

List runs, newest first, filtered by status, task, when they were created, tag, schedule or version. Without a period or dates, only the last 7 days. Returns one page; pass 'next_cursor' for more.

Inputs

Statusesstatuseslist
Only runs in these statuses. Leave empty for any.One or more of: QUEUED, DELAYED (Delayed (waiting for its start time)), PENDING_VERSION (Waiting for a deploy), DEQUEUED (Starting), EXECUTING (Running), WAITING, COMPLETED, CANCELED, FAILED, CRASHED, and 3 more.
Tasktasktext
Only runs of this task.
Created inperiodtext
Only runs created in this recent period. With no period and no dates, the last 7 days.One of: 1h (Last hour), 1d (Last 24 hours), 7d (Last 7 days (default)), 30d (Last 30 days).
Created aftercreated_afterdate and time
Only runs created at or after this time, instead of a period.
Created beforecreated_beforedate and time
Only runs created at or before this time.
Tagstagslist
Only runs with any of these tags.
Scheduleschedule_idtext
Only runs this schedule started.
Versionversiontext
Only runs of this deployed version, such as 20261015.1.
Page sizelimitnumber
How many to return, 10 to 100. Trigger.dev's default is 25.From 10 to 100.
Next page cursoraftertext
The 'next_cursor' from an earlier page of runs, for the next one.

Outputs

countnumber
How many came back
next_cursortext
Pass as 'Next page cursor' for the next page; empty on the last
runslist
The runs
Example output
{
  "count": 1,
  "next_cursor": "",
  "runs": [
    {
      "baseCostInCents": 0.0,
      "costInCents": 0.05,
      "createdAt": "2026-10-15T09:00:00.000Z",
      "delayedUntil": "",
      "durationMs": 3200,
      "env": {
        "id": "env_1234",
        "name": "prod",
        "user": ""
      },
      "expiredAt": "",
      "finishedAt": "2026-10-15T09:00:04.200Z",
      "id": "run_cm4w9x0r20001n2m3a4b5c6d",
      "idempotencyKey": "",
      "isCancelled": false,
      "isCompleted": true,
      "isExecuting": false,
      "isFailed": false,
      "isQueued": false,
      "isSuccess": true,
      "isTest": false,
      "isWaiting": false,
      "metadata": {},
      "startedAt": "2026-10-15T09:00:01Z",
      "status": "COMPLETED",
      "tags": [
        "user_123"
      ],
      "taskIdentifier": "send-welcome-email",
      "ttl": "",
      "updatedAt": "2026-10-15T09:00:04.200Z",
      "version": "20261015.1"
    }
  ]
}

List schedules

List the environment's schedules with their task, cron, time zone, whether each is on and when it next runs.

Inputs

Pagepagenumber
Which page to return, starting at 1.At least 1.
Page sizeper_pagenumber
How many to return on each page, 1 to 100.From 1 to 100.

Outputs

countnumber
How many came back
pagenumber
Which page this is
scheduleslist
The schedules
totalnumber
How many there are in all
total_pagesnumber
How many pages there are
Example output
{
  "count": 1,
  "page": 1,
  "schedules": [
    {
      "active": true,
      "deduplicationKey": "weekly",
      "environments": [
        {
          "id": "env_1234",
          "type": "PRODUCTION",
          "userName": ""
        }
      ],
      "externalId": "user_123",
      "generator": {
        "description": "At 09:00 AM, only on Monday",
        "expression": "0 9 * * 1",
        "type": "CRON"
      },
      "id": "sched_1234abcd",
      "nextRun": "2026-10-19T13:00:00.000Z",
      "task": "send-welcome-email",
      "timezone": "America/New_York",
      "type": "IMPERATIVE"
    }
  ],
  "total": 1,
  "total_pages": 1
}

Pause or resume queue

Pause a queue, so no new runs start from it (runs already going finish), or set it running again.

Inputs

Queuequeue_idtextRequired
The queue. Pick one, or give its id (it starts with queue_).
StatestatetextRequired
Paused stops new runs starting; running lets them start again.One of: paused, running (Running (resumed)).

Outputs

queueobject
The queue
Example output
{
  "queue": {
    "concurrency": {
      "base": 10,
      "current": 10,
      "overriddenAt": "",
      "overriddenBy": "",
      "override": 0
    },
    "concurrencyLimit": 10,
    "id": "queue_1234abcd",
    "name": "send-welcome-email",
    "paused": false,
    "queued": 0,
    "running": 0,
    "type": "task",
    "version": "V2"
  }
}

Replay run

Start a new run of the same task with the same payload and options as an earlier run, optionally with a different payload, start time or tags. Returns the new run's id.

Inputs

Run IDrun_idtextRequired
The run's id, which starts with run_, from 'Trigger task', 'List runs' or a trigger.
New payloadpayloadobject
A payload to use instead of the old run's. Leave empty to reuse it.
Start atstart_atdate and time
When the run should start. Leave empty to start it straight away.
Tagstagslist
Tags for the new run, instead of the old run's.

Outputs

replayed_run_idtext
The run it copied
run_idtext
The new run's id
Example output
{
  "replayed_run_id": "run_cm4w9x0r20001n2m3a4b5c6d",
  "run_id": "run_cm4wa1b2c0003n2m3x4y5z6w"
}

Set run metadata

Replace a run's metadata (its own keys and values, which the task can read and show in the dashboard) with the keys and values given.

Inputs

Run IDrun_idtextRequired
The run's id, which starts with run_, from 'Trigger task', 'List runs' or a trigger.
MetadatametadataobjectRequired
The keys and values to keep on the run.

Outputs

metadataobject
The run's metadata now
run_idtext
The run's id
Example output
{
  "metadata": {
    "progress": 50
  },
  "run_id": "run_cm4w9x0r20001n2m3a4b5c6d"
}

Trigger task

Start a run of one of your tasks with a payload, now or at a set time, in the environment the API key belongs to. Returns the run's id; the 'Run completed' trigger says when it finishes.

Inputs

TasktasktextRequired
The task to run. Pick one, or type its id as written in your code.
Payloadpayloadobject
The data the task receives, as keys and values (or JSON from an earlier step). Leave empty to send none.
Start atstart_atdate and time
When the run should start. Leave empty to start it straight away.
Tagstagslist
Up to 10 tags to find the run by later, such as user_123. Each must be under 128 characters.
Idempotency keyidempotency_keytext
Text naming this piece of work, such as order-1234. Triggering again with the same key returns the first run instead of starting another.
Machinemachinetext
The machine size to run on, instead of the one the task sets in code.One of: micro (Micro (0.25 vCPU, 0.25 GB)), small-1x (Small 1x (0.5 vCPU, 0.5 GB)), small-2x (Small 2x (1 vCPU, 1 GB)), medium-1x (Medium 1x (1 vCPU, 2 GB)), medium-2x (Medium 2x (2 vCPU, 4 GB)), large-1x (Large 1x (4 vCPU, 8 GB)), large-2x (Large 2x (8 vCPU, 16 GB)).
Expire after (minutes)expire_after_minutesnumber
If the run has not started within this many minutes, it is dropped and never runs. Leave empty to let it wait.At least 1.

Outputs

already_existedtrue/false
True when the idempotency key matched an earlier run, which is returned instead of a new one
run_idtext
The new run's id, which starts with run_
tasktext
The task it runs
Example output
{
  "already_existed": false,
  "run_id": "run_cm4w9x0r20001n2m3a4b5c6d",
  "task": "send-welcome-email"
}

Trigger task for each item

Start one run of a task for each payload in a list (up to 1,000), in one request. Returns the batch's id and the id of every run.

Inputs

TasktasktextRequired
The task to run. Pick one, or type its id as written in your code.
PayloadspayloadslistRequired
One payload per run, up to 1,000: a list of objects, such as a list from an earlier step.
Start atstart_atdate and time
When the runs should start. Leave empty to start them now.
Tagstagslist
Up to 10 tags to put on every run, such as import_42.

Outputs

batch_idtext
The batch's id, which starts with batch_
countnumber
How many runs were started
run_idslist
The new runs' ids, in order
tasktext
The task they run
Example output
{
  "batch_id": "batch_1234abcd",
  "count": 1,
  "run_ids": [
    "run_cm4w9x0r20001n2m3a4b5c6d"
  ],
  "task": "send-welcome-email"
}

Turn schedule on or off

Turn a schedule on (active) or off (inactive). An inactive schedule keeps its settings but starts no runs.

Inputs

Scheduleschedule_idtextRequired
The schedule. Pick one, or give its id (it starts with sched_).
StatestatetextRequired
On starts runs on the schedule; off stops them.One of: active (On (active)), inactive (Off (inactive)).

Outputs

scheduleobject
The schedule
Example output
{
  "schedule": {
    "active": true,
    "deduplicationKey": "weekly",
    "environments": [
      {
        "id": "env_1234",
        "type": "PRODUCTION",
        "userName": ""
      }
    ],
    "externalId": "user_123",
    "generator": {
      "description": "At 09:00 AM, only on Monday",
      "expression": "0 9 * * 1",
      "type": "CRON"
    },
    "id": "sched_1234abcd",
    "nextRun": "2026-10-19T13:00:00.000Z",
    "task": "send-welcome-email",
    "timezone": "America/New_York",
    "type": "IMPERATIVE"
  }
}

Update environment variable

Change the value of an environment variable that already exists.

Inputs

VariablenametextRequired
The variable's name. Pick one, or type it, such as DATABASE_URL.
New valuevaluetextRequired
The variable's new value.

Outputs

environmenttext
The environment, read from the API key, such as prod
nametext
The variable's name
updatedtrue/false
Always true once updated
Example output
{
  "environment": "prod",
  "name": "DATABASE_URL",
  "updated": true
}

Update schedule

Change a schedule's task, cron, time zone or your own ID. Only what is given changes. Schedules written in code can only change in code.

Inputs

Scheduleschedule_idtextRequired
The schedule. Pick one, or give its id (it starts with sched_).
Tasktasktext
A new scheduled task to run. Leave empty to keep it.
Croncrontext
A new cron, such as 0 9 * * 1 for 9:00 every Monday. Leave empty to keep it.
Time zonetimezonetext
A new time zone. Leave empty to keep it.
Your own IDexternal_idtext
A new id of your own. Leave empty to keep it.

Outputs

scheduleobject
The schedule
Example output
{
  "schedule": {
    "active": true,
    "deduplicationKey": "weekly",
    "environments": [
      {
        "id": "env_1234",
        "type": "PRODUCTION",
        "userName": ""
      }
    ],
    "externalId": "user_123",
    "generator": {
      "description": "At 09:00 AM, only on Monday",
      "expression": "0 9 * * 1",
      "type": "CRON"
    },
    "id": "sched_1234abcd",
    "nextRun": "2026-10-19T13:00:00.000Z",
    "task": "send-welcome-email",
    "timezone": "America/New_York",
    "type": "IMPERATIVE"
  }
}

On this page