Skip to main content

Cron Expression Parser API

REAL DATA

Parse any 5-field cron expression into plain English and its next run times (UTC) — full syntax support, month/weekday names, and honest errors.

Authoritative reference data or standards computation

Base URL
/api/cron
Category
Developer Tools
Capabilities
1 route
Last updated
July 29, 2026
Data source

GET /api/cron/describe Explain a cron expression and compute its next runs

Live requestRuns against the public API
No key required
GET/api/cron/describe?expression=*%2F5+*+*+*+*

Request parameters

The 5-field cron expression (minute hour day-of-month month day-of-week). Separate fields with spaces — in a URL use '+' or '%20'. Supports *, */n, a-b, a-b/n, lists, JAN-DEC and SUN-SAT names; 0 and 7 both mean Sunday.

How many upcoming run times to return (1–20).

Compute runs strictly after this instant (YYYY-MM-DD or ISO 8601). Defaults to the request time.

Advanced response options4 options

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

Return all fields except these (comma-separated).

Pretty-print the JSON response.

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples
Code samples Ready-to-copy requests in 4 languages
Choose a code sample language 
curl "https://randomapi.dev/api/cron/describe?expression=*/5+*+*+*+*"
const res = await fetch("https://randomapi.dev/api/cron/describe?expression=*/5+*+*+*+*");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/cron/describe?expression=*/5+*+*+*+*").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/cron/describe?expression=*/5+*+*+*+*"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 3
expression string required

The 5-field cron expression (minute hour day-of-month month day-of-week). Separate fields with spaces — in a URL use '+' or '%20'. Supports *, */n, a-b, a-b/n, lists, JAN-DEC and SUN-SAT names; 0 and 7 both mean Sunday.

example: expression=*/5 * * * *
count int

How many upcoming run times to return (1–20).

default: 5
allowed: 1 – 20
example: count=3
from date

Compute runs strictly after this instant (YYYY-MM-DD or ISO 8601). Defaults to the request time.

example: from=2026-01-01
Universal parameters Shared response and formatting options 4
fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=expression,description
exclude list

Return all fields except these (comma-separated).

example: exclude=fields
pretty boolean

Pretty-print the JSON response.

default: false
example: pretty=true
unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false
example: unwrap=true
Response schema Fields returned in each record 4
expression string

The expression, normalized: whitespace collapsed, names uppercased.

example: */5 * * * *

description string

The schedule in plain English.

example: Every 5 minutes

nextRuns string[] (ISO 8601 UTC)

The next `count` run times, minute-aligned, strictly after `from`.

example: ["2026-01-01T00:05:00Z","2026-01-01T00:10:00Z","2026-01-01T00:15:00Z"]

fields object

The five parsed field specs: minute, hour, dayOfMonth, month, dayOfWeek (normalized strings).

example: {"minute":"*/5","hour":"*","dayOfMonth":"*","month":"*","dayOfWeek":"*"}

Documented examples

Build-generated requests and complete responses 3
Every 5 minutes
GET /api/cron/describe?expression=*/5+*+*+*+* 
{
  "data": {
    "expression": "*/5 * * * *",
    "description": "Every 5 minutes",
    "nextRuns": [
      "2026-07-29T08:15:00Z",
      "2026-07-29T08:20:00Z",
      "2026-07-29T08:25:00Z",
      "2026-07-29T08:30:00Z",
      "2026-07-29T08:35:00Z"
    ],
    "fields": {
      "minute": "*/5",
      "hour": "*",
      "dayOfMonth": "*",
      "month": "*",
      "dayOfWeek": "*"
    }
  },
  "meta": {
    "endpoint": "cron",
    "route": "/describe",
    "params": {
      "expression": "*/5 * * * *",
      "count": 5,
      "from": "2026-07-29T08:13:22.000Z"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Mondays at 09:00, next 3 runs from a fixed date
GET /api/cron/describe?expression=0+9+*+*+MON&from=2026-01-01&count=3 
{
  "data": {
    "expression": "0 9 * * MON",
    "description": "At 09:00 on Monday",
    "nextRuns": [
      "2026-01-05T09:00:00Z",
      "2026-01-12T09:00:00Z",
      "2026-01-19T09:00:00Z"
    ],
    "fields": {
      "minute": "0",
      "hour": "9",
      "dayOfMonth": "*",
      "month": "*",
      "dayOfWeek": "MON"
    }
  },
  "meta": {
    "endpoint": "cron",
    "route": "/describe",
    "params": {
      "expression": "0 9 * * MON",
      "count": 3,
      "from": "2026-01-01"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}
Midnight on the 1st of every month
GET /api/cron/describe?expression=0+0+1+*+*&count=12 
{
  "data": {
    "expression": "0 0 1 * *",
    "description": "At 00:00 on the 1st of every month",
    "nextRuns": [
      "2026-08-01T00:00:00Z",
      "2026-09-01T00:00:00Z",
      "2026-10-01T00:00:00Z",
      "2026-11-01T00:00:00Z",
      "2026-12-01T00:00:00Z",
      "2027-01-01T00:00:00Z",
      "2027-02-01T00:00:00Z",
      "2027-03-01T00:00:00Z",
      "2027-04-01T00:00:00Z",
      "2027-05-01T00:00:00Z",
      "2027-06-01T00:00:00Z",
      "2027-07-01T00:00:00Z"
    ],
    "fields": {
      "minute": "0",
      "hour": "0",
      "dayOfMonth": "1",
      "month": "*",
      "dayOfWeek": "*"
    }
  },
  "meta": {
    "endpoint": "cron",
    "route": "/describe",
    "params": {
      "expression": "0 0 1 * *",
      "count": 12,
      "from": "2026-07-29T08:13:22.000Z"
    },
    "generatedAt": "2026-07-29T08:13:22.000Z"
  }
}

About this API

Coverage, behavior and common use cases

Coverage & behavior

Parses standard 5-field cron expressions (minute hour day-of-month month day-of-week) and answers the two questions you actually have: what does it mean and when does it run next.

Supported syntax per field: *, */n, single values, ranges a-b, stepped ranges a-b/n and comma lists — plus 3-letter names JAN–DEC and SUN–SAT (case-insensitive), with both 0 and 7 meaning Sunday. In a URL, encode the spaces as + (e.g. ?expression=*/5+*+*+*+*) or %20.

Semantics are standard cron, evaluated in UTC:

  • When both day-of-month and day-of-week are restricted, a day matches when either does (the classic OR rule).
  • nextRuns are minute-aligned instants strictly after from (which defaults to now).
  • The search stops 5 years after from: expressions that can never run (like * * 30 2 * — February 30th) return a clear 400 instead of an infinite loop, and rare-but-possible ones (like Feb 29) return fewer runs with a warning.

Invalid expressions get precise errors: wrong field counts (expected 5 fields, got 4) and out-of-range values (minute must be 0-59, got 80) name exactly what is wrong.

Use it for

  • Show a human-readable summary next to cron inputs in your scheduler UI
  • Validate user-supplied cron expressions and preview the next run times before saving
  • Debug why a job fires at the wrong time (day-of-month vs day-of-week OR semantics)

Frequently asked questions

Practical answers about this endpoint 3
What does the API return for an expression?

A human-readable description of the schedule, the parsed fields, and the upcoming run times as ISO 8601 UTC timestamps.

How many upcoming runs can I get?

count controls how many nextRuns are returned, and from anchors the schedule at any date instead of now.

Which cron syntax is supported?

The standard five-field format (minute, hour, day-of-month, month, day-of-week). An expression that doesn't parse answers 400 with the reason — never a wrong schedule.

Related APIs

Useful next tools in the catalog
Current Time API REAL DATA

Current time in any IANA timezone — UTC instant, unix seconds, local date & time, UTC offset, ISO week, day of year and a live DST flag.
Random Date Generator API MOCK DATA

Uniformly random timestamps from any date range — ISO instant, Unix seconds, date, time and weekday — with an exact weekdays-only mode and seeded results.
Date Info API REAL DATA

Real calendar facts for any date — weekday, ISO week, day of year, quarter, leap year, days in month, weekend flag and Unix timestamp. Defaults to today.
Fake Git Commit API MOCK DATA

Fake git commits — Conventional Commits or plain messages, 40-char hashes, safe author emails, dates in your range and realistic diff stats. Fully seedable.
Fake Background Job & Queue API MOCK DATA

Generate coherent queue-job fixtures with bounded attempts, retry timing, dead-letter states and queue-specific payloads.