# Trigger.dev

> 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.

App · 26 actions. Web page: https://docs.lodol.com/docs/integrations/trigger-dev

## Actions

### 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 ID (`run_id`, text, required): The run's id, which starts with run_, from 'Trigger task', 'List runs' or a trigger.
- Tags (`tags`, list, required): The tags to add, such as user_123.

**Outputs**

- `message` (text): What Trigger.dev said
- `run_id` (text): The run's id
- `tags_added` (list): The tags sent

**Example output**

```json
{
  "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 ID (`run_id`, text, required): The run's id, which starts with run_, from 'Trigger task', 'List runs' or a trigger.

**Outputs**

- `cancel_requested` (true/false): Always true; 'Get run' shows CANCELED once it has stopped
- `run_id` (text): The run's id

**Example output**

```json
{
  "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 ID (`run_id`, text, required): The run's id, which starts with run_, from 'Trigger task', 'List runs' or a trigger.
- New start time (`start_at`, date and time, required): When the run should start instead.

**Outputs**

- `run` (object): The run

**Example output**

```json
{
  "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**

- Name (`name`, text, required): The variable's name: letters, digits and underscores, such as DATABASE_URL.
- Value (`value`, text, required): The variable's value.

**Outputs**

- `created` (true/false): Always true once created
- `environment` (text): The environment, read from the API key, such as prod
- `name` (text): The variable's name

**Example output**

```json
{
  "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**

- Task (`task`, text, required): The scheduled task to run (one written with schedules.task). Pick one, or type its id.
- Cron (`cron`, text, required): 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 zone (`timezone`, text): The time zone the times in the cron are in. Defaults to UTC.
- Your own ID (`external_id`, text): Any id that means something to you, such as a customer's id. The task receives it on every run.
- Deduplication key (`deduplication_key`, text): 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**

- `schedule` (object): The schedule

**Example output**

```json
{
  "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**

- Variable (`name`, text, required): The variable's name. Pick one, or type it, such as DATABASE_URL.

**Outputs**

- `deleted` (true/false): Always true once deleted
- `environment` (text): The environment, read from the API key, such as prod
- `name` (text): The variable's name

**Example output**

```json
{
  "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**

- Schedule (`schedule_id`, text, required): The schedule. Pick one, or give its id (it starts with sched_).

**Outputs**

- `deleted` (true/false): Always true once deleted
- `schedule_id` (text): The schedule deleted

**Example output**

```json
{
  "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 ID (`batch_id`, text, required): The batch's id, which starts with batch_, from 'Trigger task for each item'.

**Outputs**

- `batch` (object): The batch

**Example output**

```json
{
  "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**

- Variable (`name`, text, required): The variable's name. Pick one, or type it, such as DATABASE_URL.

**Outputs**

- `environment` (text): The environment, read from the API key, such as prod
- `name` (text): The variable's name
- `value` (text): Its value

**Example output**

```json
{
  "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**

- Queue (`queue_id`, text, required): The queue. Pick one, or give its id (it starts with queue_).

**Outputs**

- `queue` (object): The queue

**Example output**

```json
{
  "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 ID (`run_id`, text, required): The run's id, which starts with run_, from 'Trigger task', 'List runs' or a trigger.

**Outputs**

- `run` (object): The run

**Example output**

```json
{
  "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**

- Schedule (`schedule_id`, text, required): The schedule. Pick one, or give its id (it starts with sched_).

**Outputs**

- `schedule` (object): The schedule

**Example output**

```json
{
  "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**

- Variables (`variables`, object, required): Each variable's name with its value, such as {"API_URL": "https://..."}.
- Replace existing (`override`, true/false): On replaces variables that already exist; off leaves them as they are.

**Outputs**

- `count` (number): How many were sent
- `environment` (text): The environment, read from the API key, such as prod
- `names` (list): The names sent
- `replaced_existing` (true/false): Whether variables already there were replaced

**Example output**

```json
{
  "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**

- Status (`status`, text): Only deployments in this status. One of: `DEPLOYED`, `FAILED`, `PENDING`, `BUILDING`, `DEPLOYING`, `CANCELED`, `TIMED_OUT` (Timed out).
- Created after (`created_after`, date and time): Only deployments started at or after this time.
- Created before (`created_before`, date and time): Only deployments started at or before this time. Needs 'Created after' too.
- Page size (`limit`, number): How many to return, 5 to 100. Trigger.dev's default is 20. From 5 to 100.
- Next page cursor (`after`, text): The 'next_cursor' from an earlier page of deployments, for the next one.

**Outputs**

- `count` (number): How many came back
- `deployments` (list): The deployments
- `next_cursor` (text): Pass as 'Next page cursor' for the next page; empty on the last

**Example output**

```json
{
  "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**

- `count` (number): How many came back
- `environment` (text): The environment, read from the API key, such as prod
- `variables` (list): The variables

**Example output**

```json
{
  "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**

- Page (`page`, number): Which page to return, starting at 1. At least 1.
- Page size (`per_page`, number): How many to return on each page, 1 to 100. From 1 to 100.

**Outputs**

- `count` (number): How many came back
- `page` (number): Which page this is
- `queues` (list): The queues
- `total` (number): How many there are in all
- `total_pages` (number): How many pages there are

**Example output**

```json
{
  "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**

- Statuses (`statuses`, list): 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.
- Task (`task`, text): Only runs of this task.
- Created in (`period`, text): 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 after (`created_after`, date and time): Only runs created at or after this time, instead of a period.
- Created before (`created_before`, date and time): Only runs created at or before this time.
- Tags (`tags`, list): Only runs with any of these tags.
- Schedule (`schedule_id`, text): Only runs this schedule started.
- Version (`version`, text): Only runs of this deployed version, such as 20261015.1.
- Page size (`limit`, number): How many to return, 10 to 100. Trigger.dev's default is 25. From 10 to 100.
- Next page cursor (`after`, text): The 'next_cursor' from an earlier page of runs, for the next one.

**Outputs**

- `count` (number): How many came back
- `next_cursor` (text): Pass as 'Next page cursor' for the next page; empty on the last
- `runs` (list): The runs

**Example output**

```json
{
  "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**

- Page (`page`, number): Which page to return, starting at 1. At least 1.
- Page size (`per_page`, number): How many to return on each page, 1 to 100. From 1 to 100.

**Outputs**

- `count` (number): How many came back
- `page` (number): Which page this is
- `schedules` (list): The schedules
- `total` (number): How many there are in all
- `total_pages` (number): How many pages there are

**Example output**

```json
{
  "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**

- Queue (`queue_id`, text, required): The queue. Pick one, or give its id (it starts with queue_).
- State (`state`, text, required): Paused stops new runs starting; running lets them start again. One of: `paused`, `running` (Running (resumed)).

**Outputs**

- `queue` (object): The queue

**Example output**

```json
{
  "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 ID (`run_id`, text, required): The run's id, which starts with run_, from 'Trigger task', 'List runs' or a trigger.
- New payload (`payload`, object): A payload to use instead of the old run's. Leave empty to reuse it.
- Start at (`start_at`, date and time): When the run should start. Leave empty to start it straight away.
- Tags (`tags`, list): Tags for the new run, instead of the old run's.

**Outputs**

- `replayed_run_id` (text): The run it copied
- `run_id` (text): The new run's id

**Example output**

```json
{
  "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 ID (`run_id`, text, required): The run's id, which starts with run_, from 'Trigger task', 'List runs' or a trigger.
- Metadata (`metadata`, object, required): The keys and values to keep on the run.

**Outputs**

- `metadata` (object): The run's metadata now
- `run_id` (text): The run's id

**Example output**

```json
{
  "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**

- Task (`task`, text, required): The task to run. Pick one, or type its id as written in your code.
- Payload (`payload`, object): The data the task receives, as keys and values (or JSON from an earlier step). Leave empty to send none.
- Start at (`start_at`, date and time): When the run should start. Leave empty to start it straight away.
- Tags (`tags`, list): Up to 10 tags to find the run by later, such as user_123. Each must be under 128 characters.
- Idempotency key (`idempotency_key`, text): Text naming this piece of work, such as order-1234. Triggering again with the same key returns the first run instead of starting another.
- Machine (`machine`, text): 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_minutes`, number): 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_existed` (true/false): True when the idempotency key matched an earlier run, which is returned instead of a new one
- `run_id` (text): The new run's id, which starts with run_
- `task` (text): The task it runs

**Example output**

```json
{
  "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**

- Task (`task`, text, required): The task to run. Pick one, or type its id as written in your code.
- Payloads (`payloads`, list, required): One payload per run, up to 1,000: a list of objects, such as a list from an earlier step.
- Start at (`start_at`, date and time): When the runs should start. Leave empty to start them now.
- Tags (`tags`, list): Up to 10 tags to put on every run, such as import_42.

**Outputs**

- `batch_id` (text): The batch's id, which starts with batch_
- `count` (number): How many runs were started
- `run_ids` (list): The new runs' ids, in order
- `task` (text): The task they run

**Example output**

```json
{
  "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**

- Schedule (`schedule_id`, text, required): The schedule. Pick one, or give its id (it starts with sched_).
- State (`state`, text, required): On starts runs on the schedule; off stops them. One of: `active` (On (active)), `inactive` (Off (inactive)).

**Outputs**

- `schedule` (object): The schedule

**Example output**

```json
{
  "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**

- Variable (`name`, text, required): The variable's name. Pick one, or type it, such as DATABASE_URL.
- New value (`value`, text, required): The variable's new value.

**Outputs**

- `environment` (text): The environment, read from the API key, such as prod
- `name` (text): The variable's name
- `updated` (true/false): Always true once updated

**Example output**

```json
{
  "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**

- Schedule (`schedule_id`, text, required): The schedule. Pick one, or give its id (it starts with sched_).
- Task (`task`, text): A new scheduled task to run. Leave empty to keep it.
- Cron (`cron`, text): A new cron, such as 0 9 * * 1 for 9:00 every Monday. Leave empty to keep it.
- Time zone (`timezone`, text): A new time zone. Leave empty to keep it.
- Your own ID (`external_id`, text): A new id of your own. Leave empty to keep it.

**Outputs**

- `schedule` (object): The schedule

**Example output**

```json
{
  "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"
  }
}
```
