Skip to main content
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​

FieldValuesSpecial Characters
Minute0-59* , - /
Hour0-23* , - /
Day of Month1-31* , - / L W
Month1-12 or JAN-DEC* , - /
Day of Week0-6 or SUN-SAT* , - / L #

Special Characters​

CharacterMeaningExample
*Any value* * * * * = every minute
,List separator0,30 * * * * = minute 0 and 30
-Range9-17 * * * * = hours 9 through 17
/Step values*/15 * * * * = every 15 minutes
LLast0 0 L * * = last day of month
WWeekday0 0 15W * * = nearest weekday to 15th
#Nth occurrence0 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.api.dispatch({
  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​

TimezoneRegion
America/New_YorkUS Eastern
America/ChicagoUS Central
America/DenverUS Mountain
America/Los_AngelesUS Pacific
Europe/LondonUK
Europe/ParisCentral Europe
Asia/TokyoJapan
Asia/ShanghaiChina
Australia/SydneyAustralia Eastern
UTCCoordinated 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({
  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({
  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.api.dispatch({
  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.api.dispatch({
  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({
  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​

ExpressionDescription
* * * * *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-5Weekdays at 9 AM
0 0 * * 0Every Sunday at midnight
0 0 1 * *1st of every month
0 0 L * *Last day of every month
0 0 * * 1#1First Monday of month
0 0 1 1 *January 1st

Day of Week Values​

ValueDay
0 or SUNSunday
1 or MONMonday
2 or TUETuesday
3 or WEDWednesday
4 or THUThursday
5 or FRIFriday
6 or SATSaturday

Month Values​

ValueMonth
1 or JANJanuary
2 or FEBFebruary
3 or MARMarch
4 or APRApril
5 or MAYMay
6 or JUNJune
7 or JULJuly
8 or AUGAugust
9 or SEPSeptember
10 or OCTOctober
11 or NOVNovember
12 or DECDecember

Tips and Best Practices​

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

See Also​