Step 1 of 3
Create a heartbeat monitor
Go to Add monitor → Heartbeat, name it and choose how often the job runs (e.g. every 1 day) plus a grace period.
Heartbeats
Your cron job, backup, queue worker or server calls a Perch URL every time it runs. If the call doesn't arrive on time — or reports a failure — Perch alerts you.
Heartbeats work anywhere your job can make an HTTPS request, including servers behind firewalls and NAT. Perch never connects to your server.
Set up in 3 steps
- Step 2 of 3Copy your ping URLIt is on the monitor page and looks like
https://status.ifarmer.asia/api/v1/pulse/ping/YOUR-PING-TOKEN. - Step 3 of 3Call the URL when your job finishesPick your platform under Recipes below. The monitor page shows the same recipes with your real URL filled in.
Recipes
Ping only when the job succeeds. If it fails or never runs, Perch alerts you.
Period and grace
Period is how often the job runs. Grace is how long Perch waits after that before alerting — useful when run time varies. With a 1-day period and 15-minute grace, Perch alerts if no ping arrives within 24 h 15 min of the previous one.
Ping URL reference
Every variant accepts GET, POST and HEAD and replies 200 OK.
| URL | Meaning |
|---|---|
/ping/<token> | Success — the job ran (or the server is alive). |
/ping/<token>/start | The job started. The next success / fail ping records how long it ran. |
/ping/<token>/fail | The job failed — Perch alerts right away. |
/ping/<token>/<exit code> | 0 = success, 1–255 = failure. Handy with $? in shell scripts. |
Send the job's output as the POST body (first 10 KB are kept) and it shows up in the ping history — e.g. my-job.sh 2>&1 | curl -fsS --data-binary @- https://status.ifarmer.asia/api/v1/pulse/ping/YOUR-PING-TOKEN.
Limits & security
The token in the URL is the secret — treat it like a password. You can create a new URL from the monitor page at any time (the old one stops working). Perch accepts up to 60 pings per minute per monitor; more return 429.