# Cron Expression Parser - Validate, Explain, Next Run Times (`eliai/cron-expression-parser`) Actor

Validate up to 50 cron expressions per run: plain-English description + timezone-aware next fire times (DST-correct, any IANA zone), 5/6-field, @shortcuts, names, dom/dow OR rule. $0.0008 per expression, invalid ones never charged — cheaper than measured incumbents ($0.001-$0.03).

- **URL**: https://apify.com/eliai/cron-expression-parser.md
- **Developed by:** [Broke to Built](https://apify.com/eliai) (community)
- **Categories:** Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.64 / 1,000 parsed expressions

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Cron Expression Parser — Validate, Explain & Predict Fire Times

Paste any cron expression — get back whether it is valid, what it means in plain English, and its next fire times as ISO timestamps in any IANA timezone. Handles 5-field and 6-field (seconds) syntax, `@daily`-style shortcuts, names (`MON-FRI`, `JAN`), steps, ranges, lists, and the classic day-of-month/day-of-week OR rule. Up to 50 expressions per run, online, by API, or as an agent tool via Apify MCP.

"Will this schedule fire when I think it will?" is a question people usually answer by deploying and waiting. This answers it in two seconds, timezone-correctly (DST included, via real IANA timezone math).

### What you get

- **valid** — did it parse, with the exact error when not
- **description** — plain English: "At minute(s) 0, 15, 30, 45 past hour(s) 9…17 on Monday, Tuesday…"
- **nextRuns** — the next N fire times (up to 50) as UTC ISO timestamps, computed in your chosen timezone
- **fields** — whether it was parsed as 5-field or 6-field (with seconds)
- **Fail-soft**: an invalid expression never fails the run — it returns `{ok: false, error}` and is **never charged**.

### Input

```json
{ "expression": "*/15 9-17 * * MON-FRI", "timezone": "America/New_York", "next": 5 }
```

Bulk: `{ "expressions": ["@daily", "0 3 1 * *", "30 5 * * SUN"] }`

### Output (real run)

```json
{
  "expression": "*/15 9-17 * * MON-FRI",
  "ok": true,
  "valid": true,
  "timezone": "UTC",
  "fields": 5,
  "description": "At minute(s) 0, 15, 30, 45 past hour(s) 9, 10, 11, 12, 13, 14, 15, 16, 17 on Monday, Tuesday, Wednesday, Thursday, Friday",
  "nextRuns": ["2026-08-08T09:00:00.000Z", "2026-08-08T09:15:00.000Z", "2026-08-08T09:30:00.000Z"]
}
```

An out-of-range expression like `99 * * * *` comes back `valid: false` with `"Value out of range (0-59) in minute field"` — free.

### Pricing

**$0.0008 per expression parsed.** No start fee. Invalid expressions are never charged — you pay for schedules, not typos.

Measured against store incumbents (2026-08-07): caulleonard/cron-api charges $0.001 per call, perryay/cron-expression-builder-validator $0.02 start + $0.01 per batch-validate. Validating a 50-crontab file here costs $0.04.

### Honest limits

- Standard cron dialect: 5 or 6 fields, `*`, ranges, lists, steps, month/day names, `@shortcuts`. Quartz-specific tokens (`L`, `W`, `#`, `?`) are not supported and report as invalid — honestly, rather than guessing their semantics.
- `@reboot` is rejected (it has no computable schedule).
- Fire times are exact for the timezone requested, DST transitions included (wall-clock matching via IANA timezone data, not naive offsets).

### FAQ

**Does it apply the weird day-of-month/day-of-week rule correctly?**
Yes — when both fields are restricted, standard cron fires on EITHER match (the rule most humans and some libraries get wrong). Wildcards restrict nothing.

**How are timezones handled?**
Give any IANA name (`Europe/Berlin`, `Asia/Tokyo`). Matching happens against wall-clock time in that zone; results are returned as UTC ISO timestamps you can compare and store.

**Can I validate a whole crontab in CI?**
Yes — pass all expressions as `expressions`, then fail the build if any record has `valid: false`.

**What about 6-field (seconds) cron?**
Fully supported — six fields are auto-detected and `fields: 6` marks it in the output.

**Why did some rows come back `ok: false`?**
The expression failed to parse (wrong field count, out-of-range value, unknown shortcut) — the error string is the exact reason. Never charged.

### Use from code or AI agents

```bash
curl -s "https://api.apify.com/v2/acts/EliAI~cron-expression-parser/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -X POST -H 'Content-Type: application/json' \
  -d '{"expression": "0 3 * * SUN", "timezone": "Europe/Berlin", "next": 3}'
```

Agents: connect [Apify MCP](https://mcp.apify.com) and call the `EliAI/cron-expression-parser` tool.

- **Capability:** validate, explain, and predict fire times for one or many cron expressions in any IANA timezone
- **Required input:** `expression` or `expressions`; optional `timezone` (default UTC), `next` (default 5)
- **Returns:** one record per expression; `valid`, `description`, `nextRuns` summarize it
- **Bounded:** 50 expressions, 50 fire times each; failures isolate per expression
- **Side effects:** none

# Actor input Schema

## `expression` (type: `string`):

A single cron expression to parse. Supports 5- or 6-field cron, ranges (1-5), steps (\*/15), lists (1,3,5), month/day names (JAN, MON), and @shortcuts (@daily, @hourly, @weekly, @monthly, @yearly).

## `expressions` (type: `array`):

Multiple cron expressions to parse in one run. Each item is one expression.

## `timezone` (type: `string`):

IANA timezone used to compute the next run times (e.g. America/New\_York, Europe/London, Asia/Tokyo).

## `next` (type: `integer`):

How many upcoming fire times to compute for each expression.

## `maxItems` (type: `integer`):

Maximum number of expressions to process in this run (cap).

## Actor input object example

```json
{
  "expression": "*/15 9-17 * * MON-FRI",
  "timezone": "UTC",
  "next": 5,
  "maxItems": 50
}
```

# Actor output Schema

## `results` (type: `string`):

Every item this run produced, as JSON.

## `resultsCsv` (type: `string`):

The same items as a spreadsheet-ready CSV.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "expression": "*/15 9-17 * * MON-FRI"
};

// Run the Actor and wait for it to finish
const run = await client.actor("eliai/cron-expression-parser").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "expression": "*/15 9-17 * * MON-FRI" }

# Run the Actor and wait for it to finish
run = client.actor("eliai/cron-expression-parser").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "expression": "*/15 9-17 * * MON-FRI"
}' |
apify call eliai/cron-expression-parser --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,eliai/cron-expression-parser"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/tbmsmCvhpc7u2cNmr/builds/jwzMGaphgjZpPXp6l/openapi.json