This cron expression guide explains how to schedule AI workflows safely: translate a plain-language requirement into cron syntax, account for time zones and daylight-saving changes, test the next run, and prevent duplicate, overlapping, or silently missed jobs.
Overview
Cron is a compact scheduling format used to trigger recurring jobs. In an AI workflow, the scheduled job might collect documents, summarize overnight activity, refresh an index, run an evaluation set, generate a report, or call an agent through an API. The expression controls when a task starts; your application still needs to control authentication, retries, timeout handling, output validation, and observability.
The most common Unix-style cron expression has five fields:
| Field | Allowed values | Meaning |
|---|---|---|
| Minute | 0–59 | Minute of the hour |
| Hour | 0–23 | Hour in the scheduler's time zone |
| Day of month | 1–31 | Calendar day |
| Month | 1–12 or names, depending on the scheduler | Month of the year |
| Day of week | 0–7 or names, depending on the scheduler | Day of the week; 0 and 7 commonly represent Sunday |
Special characters make schedules reusable. An asterisk means “every allowed value,” a comma lists alternatives, a hyphen defines a range, and a slash defines a step. For example, 0 2 * * * means at 02:00 every day in a five-field scheduler. Always confirm the implementation before relying on a symbol: cron dialects differ, and a valid expression in one platform may be rejected or interpreted differently in another.
Checklist by scenario
Nightly AI summarization
Start with the business requirement rather than the expression: “Run after the source system has finished publishing the previous day's records.” If the intended time is 02:00, a standard five-field example is:
0 2 * * *
- Confirm whether 02:00 is local time, UTC, or another fixed zone.
- Make sure source data is complete before the summarizer starts.
- Record the source date being summarized so a retry cannot accidentally summarize a different window.
- Use an idempotency key or run identifier to prevent duplicate summaries.
- Alert when the job fails, produces invalid structured output, or finishes unusually quickly.
Weekly report generation
For a report scheduled at 08:30 every Monday, the standard expression is:
30 8 * * 1
Before adopting it, define what “weekly” means. A report may cover the previous calendar week, the last seven completed days, or a business-specific reporting period. Store that window explicitly instead of deriving it only from the execution timestamp. This makes late runs and manual replays easier to reason about.
- Verify the day-of-week numbering used by the scheduler.
- Decide whether holidays affect execution or only report content.
- Send the report only after data validation and model-output checks pass.
- Keep a record of recipients, input version, prompt version, and generated artifact.
Frequent monitoring or evaluation
To run every 15 minutes in a five-field cron implementation, use:
*/15 * * * *
This is useful for queue checks, lightweight health probes, or recurring LLM evaluation jobs. It is not automatically suitable for long-running agent tasks. Estimate the maximum runtime and compare it with the interval. If a run can last longer than 15 minutes, add a distributed lock, use a queue with controlled concurrency, or configure a scheduler feature that prevents overlapping executions.
Migration between schedulers
Do not copy an expression without mapping its dialect. Standard cron normally uses five fields. Quartz commonly uses six or seven fields, with seconds included and different rules for the day-of-month and day-of-week fields. GitHub Actions uses a cron-like schedule in a workflow file, but execution behavior, delay, and repository settings are platform concerns. Cloud schedulers may use standard five-field syntax, a six-field variant, or provider-specific options for time zones, retries, and delivery.
| Environment | What to verify | Migration risk |
|---|---|---|
| Standard Unix cron | Five fields, host time zone, local daemon behavior | Assuming UTC or expecting built-in retry and monitoring |
| Quartz | Seconds field, optional year, special calendar syntax | Dropping or adding a field incorrectly |
| GitHub Actions | Workflow-file syntax, repository context, platform scheduling behavior | Treating it like a continuously monitored server cron job |
| Cloud scheduler | Provider dialect, configured time zone, retries, delivery target, limits | Assuming settings transfer unchanged between providers |
What to double-check
Time zones and daylight-saving changes
Every schedule has a time zone, even when it is not obvious. Identify the scheduler's configured zone and write it beside the expression in documentation. A schedule intended for “09:00 New York time” should not be described only as 0 9 * * * if the platform interprets that expression in UTC.
Daylight-saving transitions can create a local time that occurs twice or does not occur at all. A scheduler may skip, repeat, delay, or otherwise handle that run according to its own rules. For critical workflows, prefer a documented UTC schedule when a fixed interval matters, or use an explicit named time zone when a local business time matters. Test the transition behavior before the seasonal change, and design the job so a duplicate delivery is safe.
Next-run behavior
Use a cron expression builder or a trusted parser to display upcoming run times, then inspect several results rather than checking only whether the expression is syntactically valid. Test dates around month ends, leap days, daylight-saving transitions, and the interaction between day-of-month and day-of-week fields. In many traditional cron implementations, when both fields are restricted, the matching behavior is not the simple “and” relationship people expect. Confirm the platform's rule and use separate schedules or application-level filtering when clarity is more important than compact syntax.
Failure handling and overlap prevention
A schedule is not a reliability strategy. For each AI workflow, document the trigger, input window, maximum runtime, retry policy, timeout, concurrency limit, and alert destination. Make the operation idempotent where possible. If the workflow writes a report, use a stable run key and an atomic publish step. If it calls an LLM or external API, distinguish a retryable transport failure from a completed request whose response failed validation.
Track at least scheduled time, actual start time, completion time, status, input identifier, model or prompt version, and error category. These fields make it easier to investigate whether a failure came from the scheduler, authentication, source data, an API limit, or the workflow itself. For authentication-related failures, a JWT debugging checklist can help separate expired or malformed credentials from scheduling problems: review JWT claims, expiration errors, and verification checks.
Common mistakes
- Using the wrong field count: A six-field Quartz expression may be invalid in a five-field cron builder, while a five-field expression may be interpreted incorrectly where seconds are required.
- Assuming the server's time zone: Container, host, scheduler, and application time zones may differ. Record the effective zone and test it.
- Ignoring long-running jobs: A new invocation can overlap the previous one, duplicate API calls, or publish conflicting output.
- Testing syntax but not meaning: A parser can accept an expression that schedules the wrong day, month, or reporting window.
- Relying on a single alert: Monitor both failures and missing runs. A job that never starts may not generate an application-level error.
- Embedding secrets in a command: Pass credentials through the platform's secret mechanism and rotate them independently of the schedule.
- Changing a prompt and schedule together without traceability: Keep prompt, code, configuration, and schedule changes identifiable so output changes can be explained. For broader prompt governance, see the prompt versioning and governance guide.
When to revisit
Review an AI workflow schedule before seasonal planning cycles, after moving workloads between hosts or cloud providers, and whenever the source-data publication time changes. Recheck it when a prompt, model, API integration, output schema, retry policy, or workflow runtime changes. A small prompt or code change can increase processing time enough to create overlaps.
Use this practical review checklist before approving a new or modified schedule:
- Write the intended cadence, reporting window, and time zone in plain language.
- Identify the scheduler dialect and confirm its field count and special-character rules.
- Generate and inspect upcoming run times, including boundary dates.
- Test one controlled execution with representative input.
- Verify timeout, retry, lock, idempotency, and concurrency behavior.
- Confirm success, failure, and missed-run alerts.
- Record the expression, platform, time zone, owner, and last review date.
Keep the expression next to its plain-language description rather than treating the schedule as self-explanatory. When a workflow changes, repeat the checklist and compare the observed next-run times with the intended business calendar. That habit turns a compact cron expression into a maintainable part of AI workflow automation.