Cron scheduling

View as Markdown

Most monitors run on a plain interval - “every N minutes”. A cron schedule runs the check at fixed calendar times instead: “every weekday at 09:00”, “the 1st of each month”, “every 15 minutes during the working day”. Use it for checks that only make sense at certain times, or to keep a heavy check away from your peak hours. Cron times are always UTC.

Settings reference

Setting (app label)	API field (v2)	Type / allowed values	Default	Plan limits	What it does for you
Cron schedule (Main Settings, beside Interval schedule)	`cronSchedule`	A standard 5-field cron expression `minute hour day-of-month month day-of-week` (a 6-field form with seconds first is also accepted); `null` switches back to interval scheduling	None (interval scheduling)	Cron scheduling is a paid-plan feature (the switch shows Available on paid plans otherwise). A site crawl always uses cron.	Runs the check at the times the expression names, in UTC.

While a cron schedule is set, the monitor’s interval reads 0; the two schedules are alternatives, never combined.

The presets in the app

Preset	What you enter	Expression it builds
Every N minutes	N from 1 to 59	`/N * * *`
Every N hours	N from 1 to 23	`0 /N * *`
Daily	A time (UTC)	`MM HH * * *`
Weekly	One or more weekdays and a time (UTC)	`MM HH * * 1,3,5` (0 = Sunday)
Monthly	A day of the month (1-31) and a time (UTC)	`MM HH D * *`
Custom (advanced)	Any expression; suggestions include `/5 * * `, `0 9 * 1-5` (weekdays at 09:00 UTC), `0 0 1 * *` (monthly on the 1st)	As typed

Below the builder the app shows a plain-language description and Next run: - the next fire time computed by the server, so you can confirm the schedule does what you meant before saving.

Set it up in the app

On Sites, open the monitor (or Add Monitor) and expand Main Settings.
Switch the schedule from Interval schedule to Cron schedule.
Pick a preset and fill in its values, or choose Custom (advanced) and type an expression.
Check the Next run: line, then Save.

To go back to interval scheduling, switch to Interval schedule and pick an interval.

Do it with the API or MCP

Check an expression first (scope monitor:read; nothing is saved). It always answers 200:

curl -X POST https://api2.host-tracker.com/monitor/validate-cron \
  -H "Authorization: Bearer $HT_TOKEN" -H "Content-Type: application/json" \
  -d '{ "cronSchedule": "0 9 * * 1-5" }'
# { "valid": true, "next": [1759136400, 1759222800, ...] }        next 5 fire times, Unix seconds
# { "valid": false, "reason": "tooFrequent", "next": [] }

reason is one of unparseable, neverFires (no run in the next ~10 years), tooFrequent (runs closer than one minute apart) or notEntitled (your plan does not include cron scheduling).

Then set it (scope monitor:write):

curl -X PATCH "https://api2.host-tracker.com/monitor/$MONITOR_ID" \
  -H "Authorization: Bearer $HT_TOKEN" -H "Content-Type: application/json" \
  -d '{ "cronSchedule": "0 9 * * 1-5" }'

Clear it and return to an interval: { "cronSchedule": null, "interval": 300 }.
On create, send cronSchedule instead of interval.
MCP: the curated create_monitor / update_monitor tools have no cron argument - use api_request with PATCH /monitor/{id} and the body above (and POST /monitor/validate-cron to preview).

What happens next

The server computes the next fire time when you save, and the check runs at each fire time from then on. The recheck, alerts and statistics work exactly as for an interval monitor.

Limits and gotchas

UTC only. 0 9 * * * is 09:00 UTC all year; it does not follow your time zone or daylight saving time.
Minimum gap: 1 minute between two runs (1 day for a site crawl). A faster expression is refused (422 on /cronSchedule, “Schedule runs too frequently (minimum 1 minute)”).
*/N restarts every hour. */7 * * * * runs at :00, :07 … :56 and then :00 again - the last gap of each hour is shorter. Pick an N that divides 60 (or 24 for hours) for even spacing.
Monthly on day 29-31 is skipped in months that do not have that day (“Skipped in months shorter than the chosen day”).
Not for fixed-cadence types. DNSBL, Domain expiry, SSL/TLS certificate expiry and Web Risk monitors run on their own fixed schedule; a cron schedule sent for them is cleared with a warning.
Site crawl is scheduled by cron only: the app offers Daily, Weekly and Monthly, the default is weekly on Mondays at 03:00 UTC (0 3 * * 1), and a crawl monitor cannot be left without a cron.
Plan gate. Without the cron entitlement a write carrying cronSchedule is refused with 403 package_limit (“Cron scheduling is not available on your package”). If you move to a plan without it, cron-scheduled monitors are disabled until you switch them to an interval.