# Cron Schedule Calculator

> Parses a standard 5-field crontab expression (minute, hour, day of month, month, day of week with *, lists, ranges, steps and names) and lists the next run times in UTC after a start date and time, with a plain-English summary of the schedule.

- Calculator id: `cron-schedule` · Category: Developer & IT (`developer`) · Tool name: `calculate_cron_schedule`
- Canonical page: https://tttkmbb.com/developer/cron-schedule · This document: https://tttkmbb.com/developer/cron-schedule.md · JSON definition: https://tttkmbb.com/developer/cron-schedule.json

## Purpose

Parses a standard 5-field crontab expression (minute, hour, day of month, month, day of week with *, lists, ranges, steps and names) and lists the next run times in UTC after a start date and time, with a plain-English summary of the schedule.

**Use when:** You want to check when a crontab, CI or scheduler entry will fire next, or need a human-readable description of a cron expression.

**Do not use when:** The expression has 6 fields with seconds or Quartz tokens (L, W, #), you need local-time evaluation with daylight-saving rules, or you only need the day of the week of a date (use day-of-week).

## Input

| Parameter | Type | Unit | Required | Description |
| --- | --- | --- | --- | --- |
| `expression` | string |  | required | Five fields: minute hour day-of-month month day-of-week; supports *, lists (1,15), ranges (1-5), steps (*/15, 1-30/5), month and weekday names (jan, mon), 0 or 7 for Sunday and the @hourly/@daily/@weekly/@monthly/@yearly shortcuts. |
| `start_date` | date |  | optional, default "today" | UTC date from which to search (runs strictly after start_date + start_time are listed). |
| `start_time` | string |  | optional, default "00:00" | UTC time of day on start_date from which to search, HH:MM. |
| `count` | integer |  | optional, default 5 | How many upcoming run times to list. (min 1, max 20) |

## Output

| Field | Type | Unit | Description |
| --- | --- | --- | --- |
| `first_run` | string |  | First run time after the start instant (ISO 8601, UTC). |
| `next_runs` | string_list |  | The next count run times after the start instant (ISO 8601, UTC). |
| `interval_description` | string |  | Plain-English summary of the expression, e.g. 'at 09:00 on Monday–Friday'. |
| `fields` | object |  | The minute, hour, day_of_month, month and day_of_week sets the expression expands to ('*' when a field allows every value). |
| `runs_per_day_max` | integer |  | Number of hour × minute combinations that fire on a day that matches the date fields. |

## Formula

`A minute fires when minute ∈ M, hour ∈ H, month ∈ MO and the day matches: if day-of-month and day-of-week are both restricted (neither starts with *) the day matches when EITHER field matches, otherwise BOTH must match (Vixie cron)`

Times are evaluated in UTC on the proleptic Gregorian calendar; the search is capped at 5 years and a CALCULATION_ERROR is raised when no minute matches (e.g. '0 0 31 2 *'). Named months/weekdays use the first three letters, 7 means Sunday.

## Data Sources

- crontab(5) – tables for driving cron (Linux man-pages, man7.org) — https://man7.org/linux/man-pages/man5/crontab.5.html (reference, retrieved 2026-09-24)
- Cron (Wikipedia) — https://en.wikipedia.org/wiki/Cron (reference, retrieved 2026-09-24)

Data freshness: `daily` (max_age_seconds 86400). Depends on the current date when start_date is left at its default.

## API

- `GET https://tttkmbb.com/api/v1/calculate/cron-schedule?expression=…`
- `POST https://tttkmbb.com/api/v1/calculate/cron-schedule` with JSON body `{"inputs": {…}}`
- Response: unified envelope (`success`, `request`, `result.values`, `result.units`, `sources`, `freshness`, `timestamp`, `next_actions`, `links`); see https://tttkmbb.com/docs/response-format.md
- Schema: https://tttkmbb.com/api/v1/calculators/cron-schedule · OpenAPI operationId `calculate_cron_schedule` in https://tttkmbb.com/openapi.json
- Authentication: none. Rate limit: fair use, see https://tttkmbb.com/docs/rate-limits.md.

## MCP

- Server: `https://tttkmbb.com/mcp` (Streamable HTTP, JSON-RPC 2.0, no auth)
- Tool:  `run_calculator` with `{"calculator_id": "cron-schedule", "inputs": {…}}`

## Example

- Weekdays at 09:00 from Saturday 2026-09-26: inputs `{"expression":"0 9 * * 1-5","start_date":"2026-09-26","start_time":"00:00","count":5}` → `{"first_run":"2026-09-28T09:00:00Z","next_runs":["2026-09-28T09:00:00Z","2026-09-29T09:00:00Z","2026-09-30T09:00:00Z","2026-10-01T09:00:00Z","2026-10-02T09:00:00Z"],"interval_description":"at 09:00 on Monday–Friday","runs_per_day_max":1}`
- Every 15 minutes from 2026-01-01 00:00: inputs `{"expression":"*/15 * * * *","start_date":"2026-01-01","start_time":"00:00","count":3}` → `{"next_runs":["2026-01-01T00:15:00Z","2026-01-01T00:30:00Z","2026-01-01T00:45:00Z"],"interval_description":"every 15 minutes","runs_per_day_max":96}`

```
GET https://tttkmbb.com/api/v1/calculate/cron-schedule?expression=0+9+*+*+1-5&start_date=2026-09-26&start_time=00%3A00&count=5
```

## Limitations

The expression has 6 fields with seconds or Quartz tokens (L, W, #), you need local-time evaluation with daylight-saving rules, or you only need the day of the week of a date (use day-of-week). Times are evaluated in UTC on the proleptic Gregorian calendar; the search is capped at 5 years and a CALCULATION_ERROR is raised when no minute matches (e.g. '0 0 31 2 *'). Named months/weekdays use the first three letters, 7 means Sunday. All values are computed from the formula above; no measurement or live data is involved.

## FAQ

**What happens when both day-of-month and day-of-week are given?**

As in Vixie/ISC cron, '0 0 13 * 5' fires on the 13th of every month AND on every Friday (either condition). If one of the two fields is '*' (or a '*/n' step) the other one alone decides.

**Are the times in my local time zone?**

No, everything is UTC. A crontab on a server runs in that server's local zone, so shift start_time and the results by the server's UTC offset (use time-zone-converter).

**Is the start instant itself included?**

No; only runs strictly after start_date + start_time are listed, so 00:00 on the start date with '0 0 * * *' returns the following day first.

## Related

- [Day of the Week Calculator](https://tttkmbb.com/everyday/day-of-week.md) — Weekday of a specific date.
- [Unix Timestamp Converter](https://tttkmbb.com/time/unix-timestamp.md) — Epoch seconds for a run time.
- [Time Zone Converter](https://tttkmbb.com/time/time-zone-converter.md) — Shift the UTC run times to a server's local zone.