> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overwatchapp.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkin endpoint: record cron job runs without auth

> Call the checkin URL from any cron job or script to signal a successful or failed run. No authorization header required — designed for scripts.

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`.

<Note>
  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.
</Note>

<Warning>
  This endpoint only works for monitors with `type: SCHEDULED`. Calling it with the ID of an HTTP, TCP, TLS, or DNS monitor returns `404`.
</Warning>

***

## 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

<ParamField path="id" type="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`.
</ParamField>

### Query parameters

<ParamField query="status" type="string">
  Optional. Defaults to `ok`. Pass `fail` to record a failed run and immediately mark the monitor as `down`.
</ParamField>

### Response

```json theme={null}
{
  "recorded": "ok",
  "monitor": "mon_01j..."
}
```

<ResponseField name="recorded" type="string">
  `"ok"` when the checkin was recorded as successful, `"failure"` when `?status=fail` was passed.
</ResponseField>

<ResponseField name="monitor" type="string">
  The monitor ID that received the checkin.
</ResponseField>

***

## Examples

### Successful checkin

```bash theme={null}
curl https://overwatchapp.dev/api/v1/monitors/$MONITOR_ID/checkin
```

### Failed checkin

```bash theme={null}
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.

```bash theme={null}
# 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

```python theme={null}
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

```javascript theme={null}
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:

```json theme={null}
{
  "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`.

<Tip>
  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`.
</Tip>