Scheduling Patterns

Cron expressions

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)
│ │ │ │ │
* * * * *

Common patterns

Pattern	Cron	Description
Every minute	*/1 * * * *	Testing and high-frequency polling
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

curl -X POST https://api.chronos.sh/v1/schedules \
  -H "Authorization: Bearer chrns_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily tenant sync",
    "handler": "sync-tenant",
    "cron": "0 9 * * *",
    "timezone": "Europe/London"
  }'

Intervals

Use interval for fixed-frequency scheduling without calendar alignment:

curl -X POST https://api.chronos.sh/v1/schedules \
  -H "Authorization: Bearer chrns_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Health check",
    "handler": "health-check",
    "interval": { "value": 30, "unit": "second" }
  }'

Available units: second, minute, hour, day, week

Intervals vs cron

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)

Anchor-based computation

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)

Timezones

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 account’s default timezone.

DST handling

Cron schedules respect DST transitions. A 0 9 * * * schedule in America/New_York fires at 9am local time year-round: 14:00 UTC in winter, 13:00 UTC in summer.

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

Limited runs

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.

Stop conditions

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.

Archiving

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

curl -X POST https://api.chronos.sh/v1/schedules/SCHEDULE_ID/archive \
  -H "Authorization: Bearer chrns_your_api_key"

Archiving:

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

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

Updating a live schedule

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

curl -X PATCH https://api.chronos.sh/v1/schedules/SCHEDULE_ID \
  -H "Authorization: Bearer chrns_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "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.