Skip to main content
The checkin endpoint is a public URL that your scheduled jobs call to signal that they ran. When Overwatch creates a SCHEDULED monitor, it returns a checkinUrl in the response — your job hits that URL at the end of each run, and Overwatch records the heartbeat. If Overwatch stops hearing from your job within the expected window, it marks the monitor as havent_heard. If your job calls the endpoint with ?status=fail, Overwatch immediately marks it as down.
The checkin endpoint does not require an Authorization header. It is designed to be called directly from cron scripts, CI pipelines, and serverless functions without managing credentials.
This endpoint only works for monitors with type: SCHEDULED. Calling it with the ID of an HTTP, TCP, TLS, or DNS monitor returns 404.

​
Record a checkin

GET /api/v1/monitors/:id/checkin
POST /api/v1/monitors/:id/checkin
Both GET and POST behave identically. Use whichever is easiest to call from your environment. The checkinUrl returned when you create a SCHEDULED monitor is a GET-compatible URL you can paste directly into a cron job or pipeline step.

​
Path parameters

​
id
string
required
The monitor ID. This is the UUID returned in the data.id field when you created the monitor, and is also embedded in the checkinUrl.

​
Query parameters

​
status
string
Optional. Defaults to ok. Pass fail to record a failed run and immediately mark the monitor as down.

​
Response

{
  "recorded": "ok",
  "monitor": "mon_01j..."
}
​
recorded
string
"ok" when the checkin was recorded as successful, "failure" when ?status=fail was passed.
​
monitor
string
The monitor ID that received the checkin.

​
Examples

​
Successful checkin

curl https://overwatchapp.dev/api/v1/monitors/$MONITOR_ID/checkin

​
Failed checkin

curl https://overwatchapp.dev/api/v1/monitors/$MONITOR_ID/checkin?status=fail

​
Cron job (shell)

Add to your crontab to ping after the job completes. Use || to send a failure signal if the job exits non-zero. 
# Crontab entry — runs at 02:00 daily
0 2 * * * /usr/local/bin/my-export-job && \
  curl -sf https://overwatchapp.dev/api/v1/monitors/$MONITOR_ID/checkin || \
  curl -sf "https://overwatchapp.dev/api/v1/monitors/$MONITOR_ID/checkin?status=fail"

​
Python

import subprocess
import urllib.request

CHECKIN_URL = "https://overwatchapp.dev/api/v1/monitors/mon_01j.../checkin"

try:
    result = subprocess.run(["python", "export_job.py"], check=True)
    urllib.request.urlopen(CHECKIN_URL)
except Exception:
    urllib.request.urlopen(CHECKIN_URL + "?status=fail")
    raise

​
Node.js

const CHECKIN_URL = "https://overwatchapp.dev/api/v1/monitors/mon_01j.../checkin";

async function runJob() {
  try {
    await doWork();
    await fetch(CHECKIN_URL);
  } catch (err) {
    await fetch(`${CHECKIN_URL}?status=fail`);
    throw err;
  }
}

runJob();

​
Getting your checkin URL

When you create a SCHEDULED monitor, the API response includes a checkinUrl field: 
{
  "data": {
    "id": "mon_01j...",
    "type": "SCHEDULED",
    "checkinUrl": "https://overwatchapp.dev/api/v1/monitors/mon_01j.../checkin"
  }
}
You can also construct the URL yourself from any monitor ID: https://overwatchapp.dev/api/v1/monitors/{id}/checkin.
To retrieve the checkin URL for an existing monitor, call GET /api/v1/monitors/:id and build the URL from the returned id. The URL is always https://overwatchapp.dev/api/v1/monitors/{id}/checkin.