Skip to main content

​
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

​
task
string
required
The identifier of an existing scheduled task to trigger. The task must be defined with schedules.task().
​
cron
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.
​
deduplicationKey
string
required
A unique key to prevent accidentally creating duplicate schedules. If a schedule with this key already exists, the existing schedule is returned.
​
timezone
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.
​
externalId
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:
​
id
string
Schedule ID, prefixed with sched_.
​
task
string
Task identifier this schedule triggers.
​
type
string
Always IMPERATIVE for schedules created via this endpoint.
​
active
boolean
Whether the schedule is currently active. true by default.
​
deduplicationKey
string
The deduplication key provided on creation.
​
externalId
string
The external ID provided on creation, if any.
​
generator
object
CRON generator details.
​
timezone
string
IANA timezone.
​
nextRun
string
ISO 8601 timestamp of the next scheduled execution.
​
environments
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

​
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" }
  ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us