Explore documentation
  1. Welcome to Uptime 👋
  2. Frequently Asked Questions
  3. Monitoring
    1. Get started with monitoring
    2. Working with monitors
    3. Customizing monitors
    4. Monitor types
      1. Uptime monitor
      2. Keyword monitor
      3. Ping monitor
      4. Cron and heartbeat monitor
      5. Playwright monitor
      6. API monitor
      7. DNS monitor
      8. Domain expiration monitor
      9. SSL certificate monitor
      10. TCP/UDP port monitor
  4. On-call scheduling and alerting
    1. Get started with on-call
    2. Sending alerts to Slack ↗
    3. Connecting external calendars
    4. Advanced on-call setup
  5. Incidents
    1. Working with incidents
    2. Create incidents manually
    3. Post mortems
    4. Incident silencing
    5. Incident metadata
  6. Status pages
    1. Get started with status pages
    2. Working with status pages
  7. Integrations
    1. Integrating with Better Stack
  8. Team and account management
    1. Team management
    2. Account settings
    3. Audit logs
    4. Migrating to pay as you go
  9. API
    1. Get started with API
  10. Monitors API
    1. Monitors
    2. Monitor groups
    3. Heartbeats
    4. Heartbeat groups
  11. On-call & Incidents API
    1. On-call calendar
    2. On-call calendar events
    3. Escalation policies
    4. Escalation policy groups
    5. Severities
    6. Severity groups
    7. Incidents
    8. Comments
  12. Integrations API
    1. New Relic Integrations
    2. Datadog Integrations
    3. AWS CloudWatch Integrations
    4. Azure Integrations
    5. Google Monitoring Integrations
    6. Grafana Integrations
    7. Elastic Integrations
    8. Prometheus Integrations
    9. Email integrations
    10. Incoming webhooks
    11. Jira integrations
    12. Slack Integrations
    13. Outgoing Webhook integrations
    14. Splunk On-Call integrations
    15. PagerDuty Integrations
  13. Status pages API
    1. Status pages
    2. Status page sections
    3. Status page resources
    4. Status page reports
    5. Status page report updates
  14. Other API
    1. Metadata

Cron and heartbeat monitor

A heartbeat monitor helps you track periodic tasks by expecting regular requests to a unique URL.

If the expected heartbeat is not received within the specified frequency and grace period, it triggers an incident and alerts the configured on-call team.

Step-by-step setup

  1. Go to Heartbeats → Create heartbeat.
  2. Name your heartbeat — e.g. "Daily database backup".
  3. Set the Expect a heartbeat every field to match the frequency of your task.
  4. Configure the grace period, which is the extra time allowed before an incident is raised if the heartbeat is missed.
  5. Configure the On-call escalation settings.
  6. Click Save heartbeat.
  7. Copy the secret URL on the heartbeat detail page; you’ll need it in your script.

Heartbeat start

The heartbeat remains in a "Pending" state until the first request is received. The monitoring period begins from the first heartbeat received, and incidents are only raised after the "expected frequency" and "grace period" have elapsed.

Setting up a CRON and a background job

In this example, we’re using the cron-job style syntax to schedule a periodic task. Cron allows you to define tasks based on time intervals such as minutes, hours, days, etc.

To monitor a daily database backup, set up a CRON task to execute your job every day at midnight:

CRON setup for daily database backup
0 0 * * * ruby /home/deploy/backup_database.sh >/dev/null 2>&1

The CRON expression 0 0 * * * means the job will run at midnight every day.

Then, include a curl request to the heartbeat URL in your backup script:

Example of a backup script with heartbeat notification
#!/usr/bin/env bash
set -o errexit
set -o xtrace

date=`date "+%Y-%m-%d_%H:%M:%S"`
file="/dumps/uptime.betterstack.$date.dump"

time dokku postgres:export uptime > "$file"
aws s3 cp "$file" s3://uptime-dbbackups/
rm "$file"

# Notify the heartbeat URL
curl "https://uptime.betterstack.com/api/v1/heartbeat/<HEARTBEAT_TOKEN>"

Reporting failures

You can explicitly report a failure by appending /fail to the heartbeat URL:

Reporting failure to heartbeat URL
curl "https://uptime.betterstack.com/api/v1/heartbeat/<HEARTBEAT_TOKEN>/fail"

Additionally, you can include an exit code or output when reporting a failure. For example:

Reporting failure with output and exit code
backup_output=$(./run-backups.sh 2>&1)
curl -d "$backup_output" \
  "https://uptime.betterstack.com/api/v1/heartbeat/<HEARTBEAT_TOKEN>/$?"

This sends both the exit code and the script output to help diagnose the failure.

Previous article

Ping monitor

Next article

Playwright monitor