Schedule rules
Cron expression format, one-time run_at rules, timezone handling, and validation rules Nairi enforces when you create or update a scheduled job through the REST API.
Validation rules applied to the schedule, run_at and timezone fields by Create and Update.
Recurring jobs: schedule
scheduleis a 5-field cron expression (minute hour day-of-month month day-of-week).- Minimum granularity is 5 minutes. Anything more frequent is rejected.
- The cron is evaluated in the job's
timezone.
One-time jobs: run_at
run_atis an RFC 3339 timestamp (for example2026-11-07T09:00:00+02:00or2026-11-07T07:00:00Z). It must be in the future.- A job has either a
scheduleor arun_at. Sending a non-emptyscheduletogether withrun_atis rejected with400; sending neither on create is rejected too. An emptyschedulenext torun_at(the shape a one-time job is returned in) is accepted. - On update, a new
scheduleclearsrun_atand a newrun_atclearsschedule, so a job can switch between the two. Switching a one-time job to ascheduleresetslast_executed_atto now, so the cron first fires at its next occurrence rather than straight away. - On update,
run_atmust be in the future unless it is the job's currentrun_atsent back unchanged. - The job fires once at
run_at(on the next scheduler tick, so up to a minute later) and then pauses itself:is_enabledbecomesfalseandnext_run_atdisappears. - If the job cannot run at that moment (for example billing is inactive or the channel is still awaiting approval), it still runs once the blocker clears within an hour. After that it expires: it is paused without running,
last_executed_atstays beforerun_at, and it needs a newrun_atto run. - Once
run_athas passed, the job cannot be re-enabled as-is. Send a newrun_attogether withis_enabled: trueto run it again. - Pausing a one-time job before it fires and resuming it later is fine, as long as
run_atis still in the future. - "Run now" (
POST /scheduled-jobs/{id}/run) does not count as the job's run: it leavesrun_atandis_enableduntouched.
Timezone
timezonemust be a valid IANA timezone name (for exampleUTC,America/New_York,Europe/Sofia). It is required for both kinds of job; for a one-time job it only affects how the dashboard displays the time, sincerun_atcarries its own offset.