Nairi APIAutomationsScheduled jobsSchedule rules

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

  • schedule is 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_at is an RFC 3339 timestamp (for example 2026-11-07T09:00:00+02:00 or 2026-11-07T07:00:00Z). It must be in the future.
  • A job has either a schedule or a run_at. Sending a non-empty schedule together with run_at is rejected with 400; sending neither on create is rejected too. An empty schedule next to run_at (the shape a one-time job is returned in) is accepted.
  • On update, a new schedule clears run_at and a new run_at clears schedule, so a job can switch between the two. Switching a one-time job to a schedule resets last_executed_at to now, so the cron first fires at its next occurrence rather than straight away.
  • On update, run_at must be in the future unless it is the job's current run_at sent 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_enabled becomes false and next_run_at disappears.
  • 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_at stays before run_at, and it needs a new run_at to run.
  • Once run_at has passed, the job cannot be re-enabled as-is. Send a new run_at together with is_enabled: true to run it again.
  • Pausing a one-time job before it fires and resuming it later is fine, as long as run_at is still in the future.
  • "Run now" (POST /scheduled-jobs/{id}/run) does not count as the job's run: it leaves run_at and is_enabled untouched.

Timezone

  • timezone must be a valid IANA timezone name (for example UTC, 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, since run_at carries its own offset.

On this page