Create Schedule

Overview

Creates a new IMPERATIVE schedule that triggers the specified task according to a CRON expression. Imperative schedules are created programmatically (as opposed to DECLARATIVE schedules, which are declared in code using schedules.task({ cron: ... })).

Authentication with a secret key is required.

Endpoint

POST https://api.trigger.dev/api/v1/schedules

Request body

string

required

The identifier of an existing scheduled task to trigger. The task must be defined with schedules.task().

string

required

A standard 5-field CRON expression defining when the task should run. For example, "0 9 * * 1-5" runs every weekday at 9am.

string

required

A unique key to prevent accidentally creating duplicate schedules. If a schedule with this key already exists, the existing schedule is returned.

string

An IANA timezone name (e.g. "America/New_York"). Defaults to "UTC". When set, the CRON expression is evaluated in that timezone and respects daylight saving time.

string

An arbitrary string you can use to associate the schedule with a record in your own system — for example a user ID or organization ID.

Response

Returns a Schedule object:

string

Schedule ID, prefixed with sched_.

string

Task identifier this schedule triggers.

string

Always IMPERATIVE for schedules created via this endpoint.

boolean

Whether the schedule is currently active. true by default.

string

The deduplication key provided on creation.

string

The external ID provided on creation, if any.

object

CRON generator details.

Show generator fields

string

Always CRON.

string

The CRON expression.

string

Human-readable description.

string

IANA timezone.

string

ISO 8601 timestamp of the next scheduled execution.

object[]

Environments this schedule is active in.

Examples

import { schedules } from "@trigger.dev/sdk";

const schedule = await schedules.create({
  task: "my-scheduled-task",
  cron: "0 9 * * 1-5",      // every weekday at 9am
  deduplicationKey: "weekday-report",
  timezone: "America/New_York",
  externalId: "user_5678",
});

console.log(schedule.id);             // sched_1234
console.log(schedule.nextRun);        // 2024-04-02T13:00:00Z

curl -X POST "https://api.trigger.dev/api/v1/schedules" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tr_dev_1234" \
  -d '{
    "task": "my-scheduled-task",
    "cron": "0 9 * * 1-5",
    "deduplicationKey": "weekday-report",
    "timezone": "America/New_York",
    "externalId": "user_5678"
  }'

Response example

{
  "id": "sched_1234",
  "task": "my-scheduled-task",
  "type": "IMPERATIVE",
  "active": true,
  "deduplicationKey": "weekday-report",
  "externalId": "user_5678",
  "generator": {
    "type": "CRON",
    "expression": "0 9 * * 1-5",
    "description": "Every weekday at 9:00 AM"
  },
  "timezone": "America/New_York",
  "nextRun": "2024-04-02T13:00:00Z",
  "environments": [
    { "id": "cl1234", "type": "PRODUCTION" }
  ]
}

Overview

Tasks & Runs

Schedules & Queues

Waitpoints & Env Vars

Overview

Endpoint

Request body

Response

Examples

Response example

​Overview

​Endpoint

​Request body

​Response

​Examples

​Response example

Overview

Endpoint

Request body

Response

Examples

Response example