Checkin endpoint: record cron job runs without auth

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

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

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..."
}

string

"ok" when the checkin was recorded as successful, "failure" when ?status=fail was passed.

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.

Overview

Endpoints

Checkin endpoint: record cron job runs without auth

Record a checkin

Path parameters

Query parameters

Response

Examples

Successful checkin

Failed checkin

Cron job (shell)

Python

Node.js

Getting your checkin URL

​Record a checkin

​Path parameters

​Query parameters

​Response

​Examples

​Successful checkin

​Failed checkin

​Cron job (shell)

​Python

​Node.js

​Getting your checkin URL

Record a checkin

Path parameters

Query parameters

Response

Examples

Successful checkin

Failed checkin

Cron job (shell)

Python

Node.js

Getting your checkin URL