---
title: "Use this when you need to understand or schedule a 5-field cron expression."
method: POST
path: "/v1/explain_cron"
tags: ["datetime"]
---

# Use this when you need to understand or schedule a 5-field cron expression.

`POST /v1/explain_cron`

## Request

- Base URL: `https://api.clean.tools`
- URL: `https://api.clean.tools/v1/explain_cron`
- Auth: none declared

Use this when you need to understand or schedule a 5-field cron expression. Prefer this over reasoning about cron semantics yourself (a documented LLM failure mode): it correctly handles ranges, lists, steps, month/day names, and the tricky day-of-month OR day-of-week rule. Deterministic: same input, same output. Returns a plain-English description, the expanded matching values per field, and the next run times computed in UTC (pass `now` to fix the reference point, `count` for how many). Example: '*/15 9-17 * * 1-5' -> description 'At minute */15 past hour 9-17 on every weekday (Monday through Friday)'.

## Request body

- object
  - `expression` string, required: 5-field cron, e.g. "*/15 9-17 * * 1-5" (minute hour day-of-month month day-of-week).
  - `count` integer: How many upcoming run times to return (default 5).
  - `now` string: Optional ISO timestamp to compute next runs from (default: current time).

## Response `200`

Structured tool result.

- object
  - `tool` string
  - `result` object
    - `valid` boolean, required: Always true on the success result.
    - `error` unknown, required
    - `expression` string, required: The normalized 5-field cron expression.
    - `description` string, required: Plain-English description of the schedule.
    - `fields` object, required
      - `minute` integer[], required: Matching minutes, 0-59.
      - `hour` integer[], required: Matching hours, 0-23.
      - `dayOfMonth` integer[], required: Matching days of month, 1-31.
      - `month` integer[], required: Matching months, 1-12.
      - `dayOfWeek` integer[], required: Matching weekdays, 0=Sunday .. 6=Saturday (7 folds to 0).
    - `nextRuns` object[], required: Upcoming run times in UTC; length is capped by `count` (default 5).
      - `iso` string, required: ISO-8601 UTC timestamp of the run.
      - `label` string, required: Human-readable UTC label, e.g. 'Fri Jan 1 2027, 00:00 UTC'.

## Other responses

- `400`: Invalid input or the tool reported an error.
- `413`: Request body exceeds the 128 KB limit.
- `429`: Rate limit exceeded; the response carries Retry-After and RateLimit-* headers — honor them and add jitter.

---

[API](https://skmtc.dev/clean/apis/clean-tools-api.md) · [All operations](https://skmtc.dev/clean/apis/clean-tools-api/llms.txt) · [OpenAPI document](https://skmtc.dev/clean/apis/clean-tools-api/revisions/a24a01d2833c?raw)