Monitors

Use heartbeat monitors to detect missed check-ins and alert when a process stops reporting.

TrigRun monitors are heartbeat checks. Instead of TrigRun calling your service, your process calls a unique ping_url on a schedule. If no ping arrives within the expected interval plus grace period, the monitor transitions to down.

This is ideal for:

cron jobs that already run on your infrastructure
batch pipelines
backup jobs
workers that need dead-man-switch monitoring

How monitors work

Create a monitor with expected_interval_sec
TrigRun returns a unique ping_url
Your process calls that URL with GET or POST
TrigRun records the ping and moves the monitor to up
If pings stop arriving on time, the scheduler marks it down and can send notifications

Monitor states

State	Meaning
`pending`	Created, but no successful ping yet
`up`	Pings are arriving on time
`down`	Expected ping window elapsed without a ping
`paused`	Temporarily disabled

Create a monitor

curl -X POST https://api.trigrun.com/v1/monitors \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "nightly-backup",
    "expected_interval_sec": 3600,
    "grace_seconds": 120
  }'

Response:

{
  "id": "cm123...",
  "name": "nightly-backup",
  "state": "pending",
  "ping_url": "https://api.trigrun.com/v1/ping/mping_...",
  "ping_token": "mping_...",
  "expected_interval_sec": 3600,
  "grace_seconds": 120,
  "last_ping_at": null,
  "next_expected_at": "2026-03-22T10:02:00.000Z"
}

Send a ping

Both GET and POST are supported:

curl "https://api.trigrun.com/v1/ping/PING_TOKEN"

curl -X POST "https://api.trigrun.com/v1/ping/PING_TOKEN"

Successful pings return:

{ "ok": true, "state": "up" }

If the monitor is paused:

{ "ok": true, "state": "paused", "message": "Monitor is paused" }

List and inspect monitors

curl https://api.trigrun.com/v1/monitors \
  -H "Authorization: Bearer $TOKEN"

curl https://api.trigrun.com/v1/monitors/MONITOR_ID \
  -H "Authorization: Bearer $TOKEN"

Pause, resume, and delete

curl -X POST https://api.trigrun.com/v1/monitors/MONITOR_ID/pause \
  -H "Authorization: Bearer $TOKEN"

curl -X POST https://api.trigrun.com/v1/monitors/MONITOR_ID/resume \
  -H "Authorization: Bearer $TOKEN"

curl -X DELETE https://api.trigrun.com/v1/monitors/MONITOR_ID \
  -H "Authorization: Bearer $TOKEN"

View ping history

TrigRun stores recent monitor pings with IP and user agent metadata.

curl "https://api.trigrun.com/v1/monitors/MONITOR_ID/pings?limit=50&offset=0" \
  -H "Authorization: Bearer $TOKEN"

Notifications for down and recovery

Monitor rules use these events:

on_down
on_recovery

Attach a rule:

curl -X POST https://api.trigrun.com/v1/monitors/MONITOR_ID/notification-rules \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "CHANNEL_ID",
    "event": "on_down"
  }'

When a down monitor recovers on a later ping, TrigRun automatically emits on_recovery.

See Notifications for channel setup and payload examples.

CLI reference

trigrun monitors list
trigrun monitors create --name nightly-backup --interval 3600 --grace 120
trigrun monitors get MONITOR_ID
trigrun monitors pause MONITOR_ID
trigrun monitors resume MONITOR_ID
trigrun monitors delete MONITOR_ID

What monitors are not

Monitors are heartbeat checks, not multi-region synthetic uptime checks. TrigRun does not probe your website from multiple geographic regions or render browsers. If you need that style of observability, pair TrigRun monitors with a dedicated uptime product.

On this page