On this page

Monitor a cron job

Find out when a backup, sync or report job stops running, by having the job check in after every run.

Last updated

A cron job monitor waits for your job to report in. Each time the job finishes, it sends one request to Uptime; when a report doesn't arrive on schedule, Uptime alerts you.

A cron job's page

  1. Create the cron job monitor

    1. Open Cron Jobs in the sidebar and click Create Cron Job.

    2. Under Basics, give it a Name and, optionally, a Description.

    3. Under Schedule, enter the job's schedule in Cron Expression, such as 0 * * * * for every hour on the hour, and pick the Timezone it runs in (UTC by default).

    4. Set the Grace Period in seconds: how long after the scheduled time a run may still check in on time. It defaults to 300 (5 minutes) and goes from 60 seconds to 24 hours. Make it longer than the job usually takes, since the check-in comes at the end.

    5. Under Alerting, turn on Alert on Late if you want to hear as soon as a run is late, not only when it is missed. Leave Enabled on.

    6. Click Create Cron Job.

  2. Get an API key

    Check-ins are authenticated. A team owner or admin opens API Keys in the sidebar, clicks Create API Key, names it, ticks only cron-jobs:ping under Permissions, and clicks Create API Key. Copy the key now: it is shown once.

    Store it where the job can read it, such as an UPTIME_API_KEY environment variable.

  3. Make the job check in

    Open the cron job's page. Ping this monitor shows the command with this monitor's address filled in. Add it as the job's last step:

    bash title="terminal"
    curl -X POST https://uptime.sergiodxa.com/api/v1/cron-jobs/<cron-job-id>/ping \
  -H "Authorization: Bearer $UPTIME_API_KEY"

    In a crontab, chain it with && so a failed run never checks in:

    bash title="crontab"
    0 * * * * your-job.sh && curl -fsS -X POST https://uptime.sergiodxa.com/api/v1/cron-jobs/<cron-job-id>/ping -H "Authorization: Bearer $UPTIME_API_KEY"

  4. Confirm the first check-in

    After the job's next run, the check-in appears under Ping History on the cron job's page, marked On Time or Late, and the status changes from New to Healthy.

Healthy, late and missed

StatusWhenAlerts
HealthyThe last run checked in before its scheduled time plus the grace periodRecovery notice, if one was sent
LateThe grace period passed without a check-inOnly with Alert on Late
MissedThe next scheduled run's grace period passed too, so a whole run never checked inAlways

A monitor that has never received a check-in stays New until it is missed.

What does the check-in endpoint answer?

201 when the check-in is recorded. 401 when the key is missing or invalid, 403 when it lacks the cron-jobs:ping permission, 404 for an unknown ID or another team's monitor, and 409 when the cron job is disabled. Check-ins closer than 30 seconds apart for one monitor are refused with 429.

Does a check-in cost anything?

Each check-in counts as one ping toward the 100,000 included in the monthly subscription.

Up next

Documentation