Skip to content

Scheduling Patterns

The CLI examples need the chronos CLI and either your key in CHRONOS_API_KEY or a login saved by chronos auth login.

The Node.js examples use a client from the Node.js SDK (0.2.0 or later):

import { Chronos } from '@chronos.sh/sdk';
const chronos = new Chronos({ apiKey: process.env.CHRONOS_API_KEY! });

The Go examples use a client from the Go SDK (Go 1.26 or later), inside a function that returns an error. They also use the standard library’s context and os packages:

import chronos "chronos.sh/go"
client, err := chronos.NewClient(os.Getenv("CHRONOS_API_KEY"))
if err != nil {
return err
}
ctx := context.Background()

The JSON bodies on this page are the objects you pass to chronos.schedules.create. In Go, set the matching ScheduleCreateParams fields, such as Runs for runs and StopAt for stop_at. In the CLI, pass the body with --file or use the matching flags, such as --runs and --stop-at.

Use cron for calendar-based scheduling. Chronos uses standard 5-field cron syntax:

┌───────── minute (0-59)
│ ┌─────── hour (0-23)
│ │ ┌───── day of month (1-31)
│ │ │ ┌─── month (1-12)
│ │ │ │ ┌─ day of week (0-7, Sun=0 or 7)
│ │ │ │ │
* * * * *
Pattern Cron Description
Every minute */1 * * * * Testing and high-frequency polling (Team and above)
Every 15 minutes */15 * * * * Data sync, cache refresh
Every hour 0 * * * * Hourly aggregation, health checks
Daily at 9am 0 9 * * * Reports, digests
Weekdays at 9am 0 9 * * 1-5 Business-hours tasks
Monday at midnight 0 0 * * 1 Weekly cleanup, weekly reports
First of the month 0 0 1 * * Billing, monthly reports
Every 6 hours 0 */6 * * * Periodic sync without high frequency

Each plan has a minimum interval, from 10 minutes on Free down to 1 minute on Team and Business. A cron expression or interval that runs more often is rejected with plan_limit_exceeded. See Pricing & Limits.

Terminal window
chronos schedules create --name 'Daily tenant sync' --handler sync-tenant \
--cron '0 9 * * *' --timezone Europe/London

Use interval for fixed-frequency scheduling without calendar alignment:

Terminal window
chronos schedules create --name 'Health check' --handler health-check --interval 10m

Available units: second, minute, hour, day, week. In the CLI, the units are s, m, h, d and w, as in 10m.

Use interval when Use cron when
“Every N minutes/hours” regardless of clock “At 9am” or “every Monday”
Fixed frequency matters more than alignment Calendar alignment matters
Simple patterns Complex patterns (weekdays only, specific months)

Intervals compute the next run from the scheduled time, not wall-clock. This prevents drift:

interval: 1 hour
Scheduled for: 10:00:00
Actually ran: 10:00:03 (3s late)
Next run: 11:00:00 (computed from 10:00:00, not 10:00:03)

Set timezone to an IANA timezone string. This affects when cron expressions fire:

{
"name": "Daily report",
"handler": "generate-report",
"cron": "0 9 * * *",
"timezone": "America/New_York"
}

If omitted, the schedule uses your workspace’s default timezone, which an owner sets under Settings → General as “Default timezone”.

The timezone must contain a / (e.g., America/New_York, Europe/London). UTC is normalized to Etc/UTC.

Set runs to stop a schedule after a fixed number of jobs:

{
"name": "7-day onboarding sequence",
"handler": "onboarding-email",
"cron": "0 9 * * *",
"runs": 7
}

After the 7th job is created, the schedule automatically transitions to completed. No manual intervention needed.

You can update runs later via PATCH. If you reduce it below the current run_count, the schedule completes immediately.

Set stop_at to end a schedule at a specific time:

{
"name": "Holiday promotion",
"handler": "show-banner",
"interval": { "value": 1, "unit": "hour" },
"stop_at": "2026-12-26T00:00:00Z"
}

The schedule completes when the next computed run time would exceed stop_at. You can combine runs and stop_at. Whichever triggers first wins.

Archive a schedule to stop it permanently and cancel all its pending jobs:

Terminal window
chronos schedules archive SCHEDULE_ID

Archiving:

  • Sets status to archived
  • Cancels all pending, admitting, queued, ready, and retrying jobs for this schedule
  • Clears next_run_at

Currently running jobs are not affected. They finish execution normally.

Update timing, payload, or delivery config on an active schedule:

Terminal window
chronos schedules update SCHEDULE_ID --cron '0 */2 * * *' --payload '{"full":true}'

When you change cron or interval, next_run_at is recomputed immediately. Changing timezone recomputes next_run_at for cron schedules. The next job will fire on the new schedule.

You cannot update an archived or completed schedule.