Cron Monitors

Cron monitors track scheduled jobs by expecting regular check-ins. If a check-in is missed, an alert is triggered.

Endpoints

Method	Path	Description
GET	/cron_monitors	List all cron monitors
GET	/cron_monitors/:id	Get a specific monitor
POST	/cron_monitors	Create a monitor
PUT	/cron_monitors/:id	Update a monitor
DELETE	/cron_monitors/:id	Delete a monitor

Cron Monitor Object

{
  "id": "xyz789",
  "title": "Daily Backup",
  "cron_id": "550e8400-e29b-41d4-a716-446655440000",
  "cron_url": "https://beepr.io/api/cron/550e8400-e29b-41d4-a716-446655440000",
  "interval": 1440,
  "alert_group_id": "abc123",
  "status": "up",
  "check_deadline": "2024-01-16T02:00:00Z",
  "configured_at": "2024-01-15T02:00:00Z",
  "external_id": "daily-backup",
  "inserted_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Fields

Field	Type	Description
title	string	Name of the monitor (required)
interval	integer	Expected interval in minutes (required)
alert_group_id	string	Alert group to notify (required)
cron_id	string	UUID for the check-in URL (generated)
cron_url	string	Full URL for check-ins (generated)
status	string	Current status: up, down, or pending
check_deadline	string	When next check-in is expected
external_id	string	Your identifier for idempotent operations

Create a Cron Monitor

curl -X POST https://beepr.io/api/v1/cron_monitors \
  -H "Authorization: Bearer bpr_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "alert_group_id": "abc123",
    "title": "Daily Backup",
    "interval": 1440,
    "external_id": "daily-backup"
  }'

The response includes cron_url which your job should ping when it completes.

Sending Check-ins

Once created, have your cron job make a GET or POST request to the cron_url:

# In your crontab
0 2 * * * /path/to/backup.sh && curl -s https://beepr.io/api/cron/550e8400...

Example: Ansible Playbook

The API returns 201 Created for new monitors and 200 OK when updating an existing one (via external_id). You can use this to make your playbook report accurate change status:

- name: Ensure backup monitor exists
  uri:
    url: "https://beepr.io/api/v1/cron_monitors"
    method: POST
    headers:
      Authorization: "Bearer {{ beepr_api_key }}"
      Content-Type: "application/json"
    body_format: json
    body:
      alert_group_id: "{{ alert_group_id }}"
      title: "{{ inventory_hostname }} - Daily Backup"
      interval: 1440
      external_id: "{{ inventory_hostname }}-backup"
    status_code: [200, 201]
  register: monitor
  changed_when: monitor.status == 201

- name: Add check-in to crontab
  cron:
    name: "Daily backup with Beepr check-in"
    hour: "2"
    minute: "0"
    job: "/opt/backup.sh && curl -s {{ monitor.json.data.cron_url }}"

The changed_when: monitor.status == 201 line ensures Ansible shows:

• changed when a new monitor was created (201)
• ok when the monitor already existed (200)

For the complete schema, see the OpenAPI specification.