# Schedules

A check expects pings on a schedule. When the expected time passes the check is **late**; when the grace period also runs out, it goes **down** and alerts are sent.

## Intervals

An interval check expects the next success one interval after the previous success. Use it when a job runs every N minutes or hours, or when its exact clock time does not matter. The shortest interval on free accounts is one minute.

Durations accept `30s`, `5m`, `1h`, `1d`, and combinations such as `1h30m`. The API also accepts a number of seconds.

## Cron expressions

Cron checks expect a ping at each occurrence of a five-field expression, evaluated in an IANA time zone such as `Europe/Paris` or `America/Vancouver`.

```text
┌ minute (0–59)
│ ┌ hour (0–23)
│ │ ┌ day of month (1–31, or L for the last day)
│ │ │ ┌ month (1–12 or JAN–DEC)
│ │ │ │ ┌ day of week (0–7 or SUN–SAT; 0 and 7 are Sunday)
│ │ │ │ │
* * * * *
```

| Syntax | Example | Meaning |
|---|---|---|
| `*` | `* * * * *` | Every minute. |
| List | `0,30 * * * *` | Minutes 0 and 30. |
| Range | `0 9-17 * * MON-FRI` | On the hour, 09:00–17:00, weekdays. |
| Step | `*/15 * * * *` | Every 15 minutes. |
| `L` | `0 23 L * *` | 23:00 on the last day of each month. |
| `nL` | `0 10 * * 5L` | 10:00 on the last Friday of each month. |
| `n#k` | `0 10 * * 1#1` | 10:00 on the first Monday of each month. |
| Macros | `@hourly`, `@daily`, `@weekly`, `@monthly`, `@yearly` | The usual shortcuts. |

When both day of month and day of week are restricted, either can match, as in traditional cron. A field that starts with `*` counts as unrestricted.

Daylight-saving changes are handled like the cronie daemon used by most Linux distributions. For schedules limited to certain hours, a time that repeats when clocks go back matches only once, and a time skipped when clocks go forward is expected right after the change. Schedules that run every hour follow the real clock. Expressions that can never match, such as February 30, are rejected.

## Grace periods

The grace period is how long Checkpulse waits after the expected time before alerting. It also limits run time: after a `/start` signal, the job must finish within the grace period. Repeated starts do not extend that deadline.

Choose a grace period a little longer than the job's normal run time plus any delay in starting it.

## Slow runs

When a run that reports both start and finish takes more than three times the median of its recent runs, and at least 30 seconds longer, Checkpulse records a **slow** event in the check's history. It needs at least five previous timed runs.

## Changing a schedule

Changing the schedule of a check that has already been pinged restarts its deadline from the time of the change.