Skip to main content
PATCH
Create or update the project's primary schedule

Authorizations

Authorization
string
header
required

Clerk API key. Create one from your account settings under API Keys.

Path Parameters

id
string<uuid>
required

Body

application/json
name
string | null

Optional label (up to 80 characters); null clears it.

enabled
boolean
frequency
enum<string>
Available options:
daily,
weekly,
monthly
hour
integer
deprecated

Legacy: a UTC hour. Moves the schedule to the next occurrence of that hour and repeats it in UTC. Ignored when startsAt is set; prefer startsAt + timezone.

Required range: 0 <= x <= 23
startsAt
string<date-time>

The first run, as ISO 8601 with its UTC offset (e.g. 2026-11-02T09:00:00-05:00). Within the next year.

timezone
string

IANA time zone the schedule repeats in (e.g. America/New_York), so runs keep their wall-clock time across daylight saving changes. Send it with startsAt: changing an existing schedule's zone without a start time is a 400. Defaults to the current zone, or UTC for a new schedule.

scope
object

What the schedule runs. Each field is optional.

Response

Successful response

id
string | null
required

The schedule's ID; null until it is saved.

name
string | null
required

Optional label for telling a project's schedules apart.

configured
boolean
required

False until a schedule is saved for the project.

enabled
boolean
required
frequency
enum<string>
required
Available options:
daily,
weekly,
monthly
hour
integer
required
deprecated

UTC hour of startsAt (9 until configured). Prefer startsAt + timezone.

Required range: 0 <= x <= 23
startsAt
string<date-time> | null
required

The first run; later runs repeat from it in timezone. Null until configured.

timezone
string | null
required

IANA time zone the schedule repeats in. Null until configured.

nextScheduledRunAt
string<date-time> | null
required

The next run while the schedule is on; null while it is off.

upcomingRunAt
string<date-time> | null
required

When the schedule would run next, on or off: its next run, or the next occurrence of its start. Null until configured.

pauseReason
string | null
required
allowedCadences
enum<string>[]
required
Available options:
daily,
weekly,
monthly
plan
string
required
multiCountryEnabled
boolean
required

Whether the plan can schedule more than one country.

scope
object
required
estimate
object
required

Inputs for the schedule's monthly credit estimate.

anyEnabled
boolean
required

Whether any of the project's schedules is on.

soonestNextRunAt
string<date-time> | null
required

The soonest next run of the project's schedules that are on; null when none is.

scheduleCount
integer
required

How many schedules the project has.

projectPauseReason
string | null
required

Why the project's scheduled runs stopped: while none of its schedules is on, the pauseReason of the one paused most recently (latest update, then highest ID), which need not be the primary. Null while a schedule is on, or when every schedule was switched off by hand.