# Cron Job Explorer

> Paste a crontab or CronJob YAML: plain-English schedules, DST-exact next runs, herds and overlaps. Paste crontab lines (5-field, @daily macros, 6-field with seconds, Quartz with ? L W #), Kubernetes CronJob YAML or GitHub Actions schedules, plus an optional run-history CSV. Get a plain-English description and the next runs of every job in any IANA time zone with correct DST handling, minutes where many jobs start at once, overlapping schedules, jobs that run longer than their interval and failure/retry statistics.

Part of usefulweb.site (https://usefulweb.site/). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://cronjobexplorer.usefulweb.site/ (interactive tool at https://cronjobexplorer.usefulweb.site/tool)
- JSON API: POST https://cronjobexplorer.usefulweb.site/api/v1/calculate with a JSON object of inputs (schema: https://cronjobexplorer.usefulweb.site/api/v1/tool)
- OpenAPI: https://cronjobexplorer.usefulweb.site/openapi.json
- MCP (Streamable HTTP): https://cronjobexplorer.usefulweb.site/mcp - tool `cron_job_explorer`

## Inputs
- crontab (textarea, required): Crontab / schedules - One job per line. CRON_TZ=Zone lines change the zone for following jobs. A trailing "# name" or the comment line above names a job. Kubernetes CronJob / GitHub Actions YAML documents can be pasted too (separate with ---).
- history (textarea): Run history CSV (optional) - Header job,start,end,status (optional attempt). Times without offset are read in the selected time zone. Job names match the job name or appear in its command.
- timeZone (text): Time zone - IANA zone used for jobs without their own CRON_TZ / timeZone, and for displaying times.
- from (datetime): Start from (local time) - Defaults to now.
- count (integer): Next runs per job
- format (select): Expression format
- dstPolicy (select): DST handling
- horizonHours (integer): Analysis window - Window for the timeline, herd minutes and overlaps.
- herdThreshold (integer): Herd threshold - Flag minutes where at least this many jobs start together.

## Method
- Fields: minute 0–59, hour 0–23, day-of-month 1–31, month 1–12 or JAN–DEC, day-of-week 0–7 or SUN–SAT (0 and 7 = Sunday); lists, ranges, steps (*/n, a-b/n, a/n). @yearly, @monthly, @weekly, @daily/@midnight and @hourly are expanded; @reboot has no time schedule.
- Day matching follows Vixie cron/cronie: when both day-of-month and day-of-week are restricted (neither starts with "*"), a day matches if EITHER matches; if one starts with "*" (including "*/2"), both must match.
- 6-field lines with a leading seconds field are detected automatically; "?", L, W and # select Quartz semantics (day-of-week 1–7 with 1 = Sunday, L = last day, 15W = nearest weekday, 6#3 = third Friday, 5L = last Thursday, optional year field).
- Next runs are computed by walking local calendar days in the job’s time zone and converting each matching wall-clock time to UTC with Intl (IANA tz database). DST, cronie rules: fixed-time jobs scheduled in a skipped hour run right after the switch and run only once in a repeated hour; jobs with "*" in the minute or hour field follow the new wall clock (skip the gap, run in both passes of a repeated hour). The "wall-clock" policy skips non-existent times and runs repeated times twice.
- Herd minutes: within the analysis window, start times of all jobs are bucketed per minute; minutes with at least the threshold of distinct jobs are reported. Overlaps list job pairs sharing start minutes.
- Run history: per job, runs, failures, timeouts, retries (status contains "retr", attempt > 1, or a failed run followed by a new start before the next scheduled run), duration statistics, missed scheduled runs between first and last recorded start, and whether the p95 duration exceeds the shortest interval between scheduled runs (overlapping self-runs). Peak concurrency uses the p95 durations (1 minute when unknown).
- Kubernetes CronJob: metadata.name, spec.schedule, spec.timeZone, suspend and concurrencyPolicy are read; GitHub Actions on.schedule cron entries are always UTC.