Preview

Preview Feature — This feature is currently in preview and under active development. APIs and functionality may change. We recommend testing thoroughly before using in production.

Cron Expressions

Cron expressions are powerful time-based scheduling patterns that define when recurring jobs should run. Ductape uses standard 5-field cron syntax with timezone support.

Cron Syntax

A cron expression consists of 5 fields separated by spaces:

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12 or JAN-DEC)
│ │ │ │ ┌───────────── day of week (0-6 or SUN-SAT)
│ │ │ │ │
* * * * *

Field Values

Field	Values	Special Characters
Minute	0-59	`*` `,` `-` `/`
Hour	0-23	`*` `,` `-` `/`
Day of Month	1-31	`*` `,` `-` `/` `L` `W`
Month	1-12 or JAN-DEC	`*` `,` `-` `/`
Day of Week	0-6 or SUN-SAT	`*` `,` `-` `/` `L` `#`

Special Characters

Character	Meaning	Example
`*`	Any value	`* * * * *` = every minute
`,`	List separator	`0,30 * * * *` = minute 0 and 30
`-`	Range	`9-17 * * * *` = hours 9 through 17
`/`	Step values	`/15 * * *` = every 15 minutes
`L`	Last	`0 0 L * *` = last day of month
`W`	Weekday	`0 0 15W * *` = nearest weekday to 15th
`#`	Nth occurrence	`0 0 * * 1#2` = second Monday

Basic Patterns

Every X Minutes

// Every minute
schedule: { cron: '* * * * *' }

// Every 5 minutes
schedule: { cron: '*/5 * * * *' }

// Every 15 minutes
schedule: { cron: '*/15 * * * *' }

// Every 30 minutes
schedule: { cron: '*/30 * * * *' }

Hourly Schedules

// Every hour at minute 0
schedule: { cron: '0 * * * *' }

// Every hour at minute 30
schedule: { cron: '30 * * * *' }

// Every 2 hours
schedule: { cron: '0 */2 * * *' }

// Every 6 hours
schedule: { cron: '0 */6 * * *' }

Daily Schedules

// Every day at midnight
schedule: { cron: '0 0 * * *' }

// Every day at 9 AM
schedule: { cron: '0 9 * * *' }

// Every day at 6 PM
schedule: { cron: '0 18 * * *' }

// Every day at 9 AM and 6 PM
schedule: { cron: '0 9,18 * * *' }

// Every day at 9:30 AM
schedule: { cron: '30 9 * * *' }

Weekly Schedules

// Every Monday at 9 AM
schedule: { cron: '0 9 * * 1' }

// Every Friday at 5 PM
schedule: { cron: '0 17 * * 5' }

// Every Sunday at midnight
schedule: { cron: '0 0 * * 0' }

// Monday through Friday at 9 AM
schedule: { cron: '0 9 * * 1-5' }

// Weekend only at noon
schedule: { cron: '0 12 * * 0,6' }

Monthly Schedules

// First day of every month at midnight
schedule: { cron: '0 0 1 * *' }

// 15th of every month at 10 AM
schedule: { cron: '0 10 15 * *' }

// Last day of every month at 11 PM
schedule: { cron: '0 23 L * *' }

// First Monday of every month at 9 AM
schedule: { cron: '0 9 * * 1#1' }

Yearly Schedules

// January 1st at midnight
schedule: { cron: '0 0 1 1 *' }

// December 25th at 8 AM
schedule: { cron: '0 8 25 12 *' }

// First day of each quarter
schedule: { cron: '0 0 1 1,4,7,10 *' }

Timezone Support

By default, cron expressions are evaluated in UTC. Use the tz field to specify a timezone:

// Run at 9 AM Eastern Time
const job = await ductape.actions.dispatch({
  env: 'prd',
  product: 'reports',
  app: 'report-service',
  event: 'generate_report',
  input: { body: {} },
  schedule: {
    cron: '0 9 * * *',
    tz: 'America/New_York'
  }
});

// Run at 9 AM Pacific Time
schedule: {
  cron: '0 9 * * *',
  tz: 'America/Los_Angeles'
}

// Run at 9 AM London Time (handles DST automatically)
schedule: {
  cron: '0 9 * * *',
  tz: 'Europe/London'
}

Common Timezones

Timezone	Region
`America/New_York`	US Eastern
`America/Chicago`	US Central
`America/Denver`	US Mountain
`America/Los_Angeles`	US Pacific
`Europe/London`	UK
`Europe/Paris`	Central Europe
`Asia/Tokyo`	Japan
`Asia/Shanghai`	China
`Australia/Sydney`	Australia Eastern
`UTC`	Coordinated Universal Time

Complex Patterns

Business Hours

// Every 30 minutes during business hours (9 AM - 5 PM), weekdays only
schedule: {
  cron: '*/30 9-17 * * 1-5',
  tz: 'America/New_York'
}

Off-Peak Hours

// Run at 2 AM daily (off-peak)
schedule: {
  cron: '0 2 * * *',
  tz: 'America/New_York'
}

// Run every hour between midnight and 6 AM
schedule: {
  cron: '0 0-6 * * *',
  tz: 'America/New_York'
}

Multiple Times Per Day

// Run at 8 AM, 12 PM, and 6 PM
schedule: {
  cron: '0 8,12,18 * * *',
  tz: 'America/New_York'
}

Specific Days

// Every Tuesday and Thursday at 3 PM
schedule: {
  cron: '0 15 * * 2,4',
  tz: 'America/New_York'
}

// 1st and 15th of each month
schedule: {
  cron: '0 0 1,15 * *',
  tz: 'America/New_York'
}

Practical Examples

Daily Report Generation

// Generate daily sales report at 6 AM Eastern
const dailyReport = await ductape.features.dispatch({
  env: 'prd',
  product: 'analytics',
  tag: 'daily_sales_report',
  input: { reportType: 'daily' },
  retries: 3,
  schedule: {
    cron: '0 6 * * *',
    tz: 'America/New_York'
  }
});

Weekly Backup

// Backup database every Sunday at 2 AM
const weeklyBackup = await ductape.databases.action.dispatch({
  env: 'prd',
  product: 'my-app',
  database: 'main-db',
  event: 'create_backup',
  input: { query: {}, data: { type: 'full' } },
  retries: 5,
  schedule: {
    cron: '0 2 * * 0',
    tz: 'UTC'
  }
});

Monthly Billing

// Process billing on the 1st of each month at midnight
const monthlyBilling = await ductape.actions.dispatch({
  env: 'prd',
  product: 'billing',
  app: 'billing-service',
  event: 'process_monthly_billing',
  input: { body: {} },
  retries: 3,
  schedule: {
    cron: '0 0 1 * *',
    tz: 'UTC'
  }
});

Health Checks

// Run health check every 5 minutes
const healthCheck = await ductape.actions.dispatch({
  env: 'prd',
  product: 'monitoring',
  app: 'health-service',
  event: 'check_system_health',
  input: { body: {} },
  retries: 1,
  schedule: {
    cron: '*/5 * * * *'
  }
});

Data Cleanup

// Clean up expired sessions every night at 3 AM
const sessionCleanup = await ductape.databases.dispatch({
  env: 'prd',
  product: 'auth',
  database: 'sessions-db',
  operation: 'delete',
  input: {
    table: 'sessions',
    where: {
      expires_at: { $LT: '$Now()' }
    }
  },
  schedule: {
    cron: '0 3 * * *',
    tz: 'UTC'
  }
});

Cron Expression Reference

Quick Reference Table

Expression	Description
`* * * * *`	Every minute
`/5 * * *`	Every 5 minutes
`0 * * * *`	Every hour
`0 /2 * *`	Every 2 hours
`0 0 * * *`	Every day at midnight
`0 9 * * *`	Every day at 9 AM
`0 9 * * 1-5`	Weekdays at 9 AM
`0 0 * * 0`	Every Sunday at midnight
`0 0 1 * *`	1st of every month
`0 0 L * *`	Last day of every month
`0 0 * * 1#1`	First Monday of month
`0 0 1 1 *`	January 1st

Day of Week Values

Value	Day
0 or SUN	Sunday
1 or MON	Monday
2 or TUE	Tuesday
3 or WED	Wednesday
4 or THU	Thursday
5 or FRI	Friday
6 or SAT	Saturday

Month Values

Value	Month
1 or JAN	January
2 or FEB	February
3 or MAR	March
4 or APR	April
5 or MAY	May
6 or JUN	June
7 or JUL	July
8 or AUG	August
9 or SEP	September
10 or OCT	October
11 or NOV	November
12 or DEC	December

Tips and Best Practices

Use Timezones - Always specify tz for business-critical schedules to handle DST correctly
Avoid Minute 0 - Many systems schedule jobs at the top of the hour; consider using offset minutes (e.g., 5 * * * *)
Test Expressions - Use online cron validators to verify your expressions before deploying
Consider Load - Spread out jobs throughout the hour/day to avoid resource spikes
Use Intervals for Simple Cases - For simple intervals (every X minutes/hours), use every instead of cron

Cron Syntax​

Field Values​

Special Characters​

Basic Patterns​

Every X Minutes​

Hourly Schedules​

Daily Schedules​

Weekly Schedules​

Monthly Schedules​

Yearly Schedules​

Timezone Support​

Common Timezones​

Complex Patterns​

Business Hours​

Off-Peak Hours​

Multiple Times Per Day​

Specific Days​

Practical Examples​

Daily Report Generation​

Weekly Backup​

Monthly Billing​

Health Checks​

Data Cleanup​

Cron Expression Reference​

Quick Reference Table​

Day of Week Values​

Month Values​

Tips and Best Practices​

See Also​