interval

The interval directive describes when a recurring task fires. It has two shapes:

• A shorthand one-liner that takes either a duration or a cron expression and nothing else.
• A block form that takes the same base value plus optional modifiers.

For background on writing cron expressions and running tasks at regular intervals, see Cron and interval timers.

Parameters:

• duration - fixed period (for example every 5 minutes). Mutually exclusive with cron.
• cron - cron expression evaluated against a wall clock. Mutually exclusive with duration.
• random - optional jitter applied on top of duration or cron.
• time-zone - optional time zone for cron; not valid with duration.

Syntax Variations

Duration shorthand

interval 5m;

Cron shorthand

interval "0 0 * * * * *";

Block form with duration and random jitter

interval {
    duration 5m;
    random 30s;
}

Block form with cron and random jitter

interval {
    cron "0 30 * * * * *";
    random 10s;
}

Block form with cron and a time zone

interval {
    cron "0 0 2 * * * *";
    time-zone "Europe/Helsinki";
}

random shifts each scheduled run by a uniformly random offset in the range +/- random/2, with sub-second precision. The offset is centered on the base time, so runs may fire slightly before or after it. Use it on schedules shared across features or instances to avoid synchronised spikes on backing services.

When combined with duration, random must be smaller than 2 * duration; values at or above that bound can reorder consecutive ticks and produce burst fires, and are rejected at parse time. For cron schedules pick random smaller than the smallest gap between scheduled runs.

time-zone selects the zone in which the cron expression is evaluated. When omitted (or set to "local"), it is the Radiator local zone. Use "UTC", "Europe/Helsinki", "America/New_York". Named zones follow their own DST (daylight savings time) rules independent of the host. Invalid names and combining time-zone with duration are rejected at parse time.

Cron Format

Cron uses seven fields:

1. second
2. minute
3. hour
4. day-of-month
5. month
6. day-of-week
7. year

For duration suffixes (ms, s, m, h, and others), see Duration Units.