docs/getting started

getting started

set up your first monitor in under 30 seconds.

S-01

create an account

go to cronvigil.com/register and sign up with your email or github account. no credit card required.

S-02

create your first monitor

from your dashboard, click new monitor. fill in:

name — a label for this job (e.g. daily-backup)
interval — how often the job runs (e.g. every 1 hour)
grace period — how late a ping can arrive before we alert (default: 5 minutes)

S-03

copy your ping url

after saving, you'll see a unique ping url like:

https://cronvigil.com/p/YOUR_SLUG

this url is what your cron job will call when it finishes successfully.

S-04

add to your cron job

append a curl call to the end of your cron command using the && operator. the ping is only sent if your command succeeds.

bash

# basic usage
your-command && curl -fsS https://cronvigil.com/p/YOUR_SLUG

# crontab example (runs every hour)
0 * * * * /usr/local/bin/backup.sh && curl -fsS https://cronvigil.com/p/YOUR_SLUG

# silence curl output completely
your-command && curl -fsS --retry 3 -o /dev/null https://cronvigil.com/p/YOUR_SLUG

the -fsS flags: -f fail silently on HTTP errors, -s silent mode, -S still show errors if -s is set.

S-05

report job duration (optional)

cronvigil can also track how long your job takes. send the duration in milliseconds via the duration_ms query param, or as JSON in a POST body. it shows up as avg response on your dashboard.

bash

# query param (works with GET or POST)
curl -fsS "https://cronvigil.com/p/YOUR_SLUG?duration_ms=1240"

# measure inside a shell script
start=$(date +%s%3N)
your-command
end=$(date +%s%3N)
curl -fsS "https://cronvigil.com/p/YOUR_SLUG?duration_ms=$((end-start))"

# JSON body
curl -fsS -X POST https://cronvigil.com/p/YOUR_SLUG \
  -H "Content-Type: application/json" \
  -d '{"duration_ms": 1240}'

must be a positive integer up to 86400000 (24h). invalid values are silently ignored — the ping itself still counts.

S-06

verify it works

after your first ping arrives, the monitor status changes to up. you can also trigger a test ping manually from the dashboard.

cronvigil will wait up to interval + grace period before marking the monitor as missed and sending an alert.

what happens when a ping is missed

1. your monitor's deadline passes (interval + grace period).

2. cronvigil marks the monitor as missed.

3. an alert is sent to all configured channels (email by default).

4. the monitor stays in missed state until the next successful ping arrives.

code examples

bash

#!/bin/bash
# run your job, then ping on success
/usr/local/bin/my-backup-script.sh \
  && curl -fsS https://cronvigil.com/p/YOUR_SLUG

python

import urllib.request

def run_job():
    # your job logic here
    pass

def ping_success(slug: str):
    url = f"https://cronvigil.com/p/{slug}"
    urllib.request.urlopen(url, timeout=10)

if __name__ == "__main__":
    run_job()
    ping_success("YOUR_SLUG")

node.js

javascript

const https = require('https');

function runJob() {
  // your job logic here
}

async function pingSuccess(slug) {
  await fetch(`https://cronvigil.com/p/${slug}`);
}

(async () => {
  runJob();
  await pingSuccess('YOUR_SLUG');
})();

php

<?php

function runJob(): void {
    // your job logic here
}

function pingSuccess(string $slug): void {
    $url = "https://cronvigil.com/p/{$slug}";
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 10);
    curl_exec($ch);
    curl_close($ch);
}

runJob();
pingSuccess('YOUR_SLUG');

← back to docs next: alert channels →