# Ping a Heartbeat Monitor From Cron With curl: Flags and Pitfalls

By Dan Ochoa · Published 2026-11-16 · Updated 2026-11-16
Canonical: https://cronradar.com/blog/curl-cron-heartbeat

> Send a cron heartbeat with curl the right way: -fsS, --max-time, retries, keeping the exit code, && vs ;, escaping % in crontab, and keeping the API key out.

**For a cron heartbeat, use `curl -fsS -m 5 -o /dev/null` after `&&`, so the ping is sent only when the job succeeds, gives up after five seconds, and prints an error only when something is wrong.** Keep the API key in a file curl reads, not on the crontab line, and escape every `%` in the crontab as `\%` or move the logic into a script. For start, complete, and fail reports with the job's exit code, use a wrapper script that returns the job's own exit status.

This guide covers curl 7.76 and later, cronie, and Debian's cron, checked against the [curl man page](https://curl.se/docs/manpage.html) and [crontab(5)](https://man7.org/linux/man-pages/man5/crontab.5.html) on November 16, 2026. Examples use CronRadar's ingestion API; the curl and cron details apply to any heartbeat service. For why a heartbeat catches failures that logs don't, see [cron dead man's switch](https://cronradar.com/blog/cron-dead-mans-switch).

## The One-Line Heartbeat

```text
30 2 * * * /opt/backup.sh && curl -fsS -m 5 -o /dev/null -K /etc/cronradar/curl.conf https://cron.life/api/v1/ping/nightly-backup
```

`/etc/cronradar/curl.conf` holds one line, `user = "ck_app_12345_abcdef:"`, so curl authenticates with HTTP Basic using the application's API key as the username and an empty password. `nightly-backup` is the monitor key. This form reports to a monitor that already exists; creating one from the ping needs the `schedule` parameter, covered below.

## What Each Flag Does

| Flag                   | Effect                                                              | Why it matters for a heartbeat                                           |
| ---------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `-f`, `--fail`         | Exit 22 on an HTTP status of 400 or more, without printing the body | A rejected ping (bad key, bad schedule) is an error, not a quiet success |
| `-s`, `--silent`       | No progress meter, no messages                                      | Keeps cron from mailing a progress bar                                   |
| `-S`, `--show-error`   | With `-s`, still print an error message                             | You hear about failures, and only failures                               |
| `-m 5`, `--max-time 5` | Cap each transfer at five seconds                                   | A hung network can't hold the job open                                   |
| `-o /dev/null`         | Discard the response body                                           | A successful ping produces no output to mail                             |
| `-K file`, `--config`  | Read options from a file                                            | Keeps the key off the command line                                       |

By default, curl treats any HTTP response as success: a 401 for a revoked key exits 0, and nothing notices the monitor has stopped receiving pings. `-f` changes that.

### --fail-with-body Needs curl 7.76.0

`--fail-with-body` fails on the same statuses as `--fail` but keeps the response body, which for CronRadar is a JSON error such as `MONITOR_NOT_FOUND` with a message. It was added in curl 7.76.0, and the two options are mutually exclusive. Older distributions (RHEL 8 and Ubuntu 20.04 ship curl 7.61 and 7.68) reject it as an unknown option, which makes the whole ping fail every time. Check with `curl --version`, and use `--fail-with-body` while testing by hand, `-f` in production if your fleet has old hosts.

### Timeouts

`--max-time` limits each transfer, connection included. `--connect-timeout` limits only the connection phase and isn't a substitute: a server that accepts the connection and never answers is stopped only by `--max-time`. Five seconds is plenty for one small request and matches the timeout CronRadar's own SDKs use.

### Retries, and Their Caveats

`--retry N` retries "transient" errors: a timeout, or an HTTP 408, 429, 500, 502, 503, 504, 522, or 524 response. The first retry waits one second and each later one doubles the wait, and curl honors a `Retry-After` header. Three things to know before adding it:

- **`--max-time` resets on each retry.** `-m 5 --retry 3` can take well over 20 seconds. Add `--retry-max-time 15` to bound the total; a transfer already running is allowed to finish, so the real ceiling is a little higher.
- **A refused connection isn't transient.** If the network isn't up yet, add `--retry-connrefused`.
- **`--retry-all-errors` (curl 7.71.0) retries everything,** including a 400 for a malformed request or a 401 for a revoked key, which will fail identically each time. The man page calls it "the sledgehammer of retrying" and warns about "sending or receiving duplicate data." For a heartbeat, plain `--retry` is the better choice.

A retry can also deliver a request twice: the first attempt may have reached the server before the timeout fired. For a plain heartbeat that's harmless. For lifecycle events, send an `Idempotency-Key` header; CronRadar returns the original result for a duplicate key instead of applying it again.

```text
30 2 * * * /opt/backup.sh && curl -fsS -m 5 --retry 2 --retry-max-time 15 -o /dev/null -K /etc/cronradar/curl.conf https://cron.life/api/v1/ping/nightly-backup
```

## && Versus ;

The operator between the job and curl decides what the ping means.

| Line                     | When curl runs          | What the heartbeat proves                        |
| ------------------------ | ----------------------- | ------------------------------------------------ |
| `job && curl ...`        | Only if the job exits 0 | The job ran and succeeded                        |
| `job ; curl ...`         | Always                  | Only that cron fired; failures look like success |
| `job \|\| curl .../fail` | Only if the job fails   | Failures, but not missed runs on its own         |

Use `&&`. With `;`, a backup that fails every night still pings every night, and the monitor stays healthy. With `&&`, a failed job sends nothing, and the monitor alerts once the expected time plus the grace period passes.

The line's exit status becomes curl's when curl runs and the job's when it doesn't. Cron itself doesn't act on exit status, so that's harmless on a crontab line, but it matters as soon as the line moves into a script that something else checks. The wrapper below keeps the job's status.

`&&` only works if the job's exit code is honest. A script that ends with `echo done`, or a pipeline whose last command succeeds, exits 0 after a failure; [cron shell script best practices](https://cronradar.com/blog/cron-shell-script-best-practices) covers `set -e` and `pipefail`.

## Escape % in the Crontab

In a crontab command, an unescaped `%` is changed into a newline, and everything after the first one is sent to the command as standard input ([crontab(5)](https://man7.org/linux/man-pages/man5/crontab.5.html)). A heartbeat line breaks in two common ways:

```text
# Broken: cron cuts the command at the first %, so curl never sees the rest.
0 3 * * * /opt/export.sh && curl -fsS -m 5 "https://cron.life/api/v1/ping/export?schedule=0%203%20*%20*%20*"
0 3 * * * /opt/export.sh --date "$(date +%F)" && curl ...

# Works: each % escaped with a backslash.
0 3 * * * /opt/export.sh --date "$(date +\%F)" && curl ...
```

URL-encoded query strings and `date` formats are full of `%`. Escaping each one works, but the line gets hard to read and easy to break on the next edit. Once a heartbeat needs a schedule, a run ID, or a failure message, put it in a script, where `%` is just a character.

## Keep the API Key Out of the Crontab

Three places a key on the crontab line ends up:

- **Mail.** cronie and Debian's cron put crontab variables in the headers of the mail they send with a job's output, as [cron "No MTA installed"](https://cronradar.com/blog/cron-no-mta-installed) shows from the source. `CRONRADAR_API_KEY=...` at the top of a crontab leaks there.
- **Process listings and logs.** A key in the URL path (`/ping/{key}/{api_key}`) is visible in `ps` while curl runs and in any proxy log on the way. Basic authentication keeps it out of the URL.
- **The command line itself.** Even `-u "ck_app_...:"` is exposed briefly: the curl man page says it hides the argument from process listings where it can, but it is "still visible for a moment before being cleared," and recommends reading such data from a file.

So read the key from a file only the job's account can read:

```bash
sudo install -d -m 0750 -o backup -g backup /etc/cronradar
sudo install -m 0600 -o backup -g backup /dev/null /etc/cronradar/curl.conf
sudoedit /etc/cronradar/curl.conf      # user = "ck_app_12345_abcdef:"
```

`-K /etc/cronradar/curl.conf` loads it without the key ever appearing in an argument. In a script, reading the key from a file and passing `--user "$CRONRADAR_API_KEY:"` keeps it out of the crontab and the URL, though not entirely out of process listings; `-K` avoids that too, which is why the wrapper below uses it. [Cron environment variables](https://cronradar.com/blog/cron-environment-variables) shows other ways to load secrets for cron jobs. Use a separate CronRadar application and key per environment, so a staging host can't report to production monitors.

## Start, Complete, and Fail With run_id

A success-only ping can't tell a failed run from a missed one, and it says nothing about how long the job took. Reporting start, complete, and fail adds both, and a `fail` report alerts immediately instead of waiting for the grace period. This wrapper follows the lifecycle pattern in CronRadar's API reference: it reports start, runs the job, reports the outcome with the exit code, and exits with the job's own status:

```sh
#!/bin/sh
# /opt/backup-monitored.sh: run the backup and report its lifecycle to CronRadar.
url="https://cron.life/api/v1/ping/nightly-backup"
run_id="nightly-backup-$(date +%s)-$$"

report() {
  event=$1
  shift
  curl --fail --silent --show-error --max-time 5 --output /dev/null \
    --request POST --get --config /etc/cronradar/curl.conf \
    --header "Idempotency-Key: $run_id-$event" \
    --data-urlencode "schedule=30 2 * * *" \
    --data-urlencode "gracePeriod=900" \
    --data-urlencode "run_id=$run_id" \
    "$@" "$url/$event" || true
}

report start
/opt/backup.sh
rc=$?
if [ "$rc" -eq 0 ]; then
  report complete
else
  report fail --data-urlencode "message=backup.sh exited with code $rc"
fi
exit "$rc"
```

How it fits together:

- **`--get` with `--data-urlencode`** puts each parameter in the query string, URL-encoded, so `30 2 * * *` arrives intact; `--request POST` makes it a POST, which the API recommends for lifecycle events. CronRadar accepts GET too.
- **`schedule`** on every report means the first run creates the monitor, and a monitor deleted by accident comes back on the next run. `gracePeriod` is in seconds, minimum 60.
- **`run_id`** pairs the start with its outcome, so overlapping runs don't get mixed up. It's at most 128 characters.
- **`message`** goes only on `fail`, at most 1,000 characters. Send the exit code and a short reason, never logs, secrets, or customer data.
- **`--config`** supplies the key for Basic authentication from the file created above.
- **`|| true` and `--max-time 5`** keep a monitoring outage from failing the job or stalling it for more than a few seconds per report.
- **`exit "$rc"`** returns the backup's own status, so anything that checks the script still sees the real result.

The crontab line is just `30 2 * * * /opt/backup-monitored.sh`, with no `%` and no key.

Test it by hand as the job's account before trusting it. Swap `--fail` for `--fail-with-body` and drop `--output /dev/null` in a copy, and you'll see CronRadar's JSON response, or its error and reason.

## What You Get From CronRadar

There's no CronRadar package for crontab and no discovery of crontab entries; each job reports with its own monitor key and schedule, as above. In return, a monitor that knows the schedule catches every way the job can go wrong. After the expected time plus the grace period with no report, the monitor goes from `warning` to `critical` and alerts by email, Slack, webhook, Discord, or PagerDuty. A `fail` report alerts immediately, and a start with no finish is flagged as stuck. Schedules are read in the application's time zone, an IANA name set in its settings (UTC when unset), so set it to the server's zone. For jobs inside a framework, the [Laravel](https://cronradar.com/laravel), [Celery](https://cronradar.com/celery), [Hangfire](https://cronradar.com/hangfire), and [Quartz.NET](https://cronradar.com/quartz) integrations report without any curl. Plans are on the [pricing](https://cronradar.com/pricing) page.

## Frequently Asked Questions

### What curl flags should I use for a cron heartbeat?

`-fsS -m 5 -o /dev/null`: fail on HTTP errors, stay quiet unless there's an error, give up after five seconds, and discard the response body. Add `--retry 2 --retry-max-time 15` if the network is flaky, and `-K` with a config file to supply the key.

### Why does my curl command work in the shell but not in crontab?

Usually a `%`. Cron turns each unescaped `%` into a newline and sends the rest as standard input, which cuts URL-encoded query strings and `date +%F` short. Escape it as `\%` or move the command into a script. A minimal `PATH` in cron is the other common cause; use the full path to curl if it isn't in `/usr/bin`.

### Should I use && or ; before the heartbeat curl?

`&&`. It sends the ping only when the job exits 0, so a failing job stops pinging and the monitor alerts. With `;` the ping is sent after every run, including failed ones.

### Does --retry make a heartbeat more reliable?

For transient errors such as timeouts and 5xx responses, yes, but bound it with `--retry-max-time`, because `--max-time` resets on each attempt. Avoid `--retry-all-errors`, which also retries requests that will fail the same way each time, like a bad key.

### How do I keep the API key out of my crontab?

Put it in a file only the job's account can read and load it with `curl -K`, or read it into a variable in a wrapper script. A key in the crontab can end up in cron's mail headers, and a key in the URL is visible in process listings and proxy logs.
