Pings & Flips

Use these endpoints to review ping history, status transitions (flips), and to pause or unpause monitoring for a check.

Pause or unpause a check

PATCH /api/v1/checks/{uuid}/pause

Pauses or resumes monitoring for a check. While paused, missed pings do not trigger alerts.

Request body

Field	Type	Default	Description
`paused`	boolean	true	`true` to pause, `false` to resume monitoring

# Pause a check
curl -X PATCH https://watchcron.com/api/v1/checks/YOUR-UUID/pause \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"paused": true}'

# Resume monitoring
curl -X PATCH https://watchcron.com/api/v1/checks/YOUR-UUID/pause \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"paused": false}'

// Pause a check
$response = Http::withToken('YOUR_API_KEY')
    ->patch("https://watchcron.com/api/v1/checks/{$uuid}/pause", [
        'paused' => true,
    ]);

// Resume monitoring
$response = Http::withToken('YOUR_API_KEY')
    ->patch("https://watchcron.com/api/v1/checks/{$uuid}/pause", [
        'paused' => false,
    ]);

# Pause a check
response = requests.patch(
    f"https://watchcron.com/api/v1/checks/{uuid}/pause",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"paused": True},
)

# Resume monitoring
response = requests.patch(
    f"https://watchcron.com/api/v1/checks/{uuid}/pause",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"paused": False},
)

// Pause a check
await fetch(`https://watchcron.com/api/v1/checks/${uuid}/pause`, {
  method: "PATCH",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ paused: true }),
});

Returns 200 OK with the updated check object. When paused, the status changes to paused. When resumed, the status resets to new (waiting for the next ping).

Pausing is useful during deployments or planned maintenance — it prevents false alerts while your jobs are intentionally not running.

List pings

GET /api/v1/checks/{uuid}/pings

Returns the ping history for a check, ordered newest first.

Query parameters

Parameter	Type	Default	Description
`per_page`	integer	25	Results per page
`page`	integer	1	Page number

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://watchcron.com/api/v1/checks/YOUR-UUID/pings?per_page=50"

$response = Http::withToken('YOUR_API_KEY')
    ->get("https://watchcron.com/api/v1/checks/{$uuid}/pings", [
        'per_page' => 50,
    ]);

$pings = $response->json('data');

response = requests.get(
    f"https://watchcron.com/api/v1/checks/{uuid}/pings",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"per_page": 50},
)

pings = response.json()["data"]

const response = await fetch(
  `https://watchcron.com/api/v1/checks/${uuid}/pings?per_page=50`,
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);

const { data: pings } = await response.json();

Response 200 OK

JSON

{
  "data": [
    {
      "type": "success",
      "remote_ip": "203.0.113.42",
      "duration_ms": 4523,
      "created_at": "2026-09-14T02:00:12Z"
    },
    {
      "type": "start",
      "remote_ip": "203.0.113.42",
      "duration_ms": null,
      "created_at": "2026-09-14T01:59:58Z"
    }
  ],
  "meta": {
    "pagination": {
      "total": 1847,
      "per_page": 50,
      "current_page": 1,
      "last_page": 37
    }
  }
}

Ping object fields

Field	Type	Description
`type`	string	Ping type: `success`, `start`, `fail`, or `log`
`remote_ip`	string	IP address that sent the ping
`duration_ms`	integer\|null	Job duration in milliseconds (calculated between `start` and `success` pings)
`created_at`	string	ISO 8601 timestamp when the ping was received

Ping types explained

Type	Purpose	When to use
`success`	Reports job completed successfully	At the end of your job: `curl https://watchcron.com/ping/UUID`
`start`	Signals job has started running	At the beginning: `curl https://watchcron.com/ping/UUID/start`. Enables duration tracking.
`fail`	Reports explicit failure	In error handlers: `curl https://watchcron.com/ping/UUID/fail`. Triggers alert immediately.
`log`	Attaches log output to the check	POST body is stored (max 100 KB). Useful for debugging.

List status flips

GET /api/v1/checks/{uuid}/flips

Returns the history of status transitions for a check. A “flip” is recorded each time a check’s status changes (e.g. from up to down, or from down to up).

Query parameters

Parameter	Type	Default	Description
`per_page`	integer	25	Results per page
`page`	integer	1	Page number

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://watchcron.com/api/v1/checks/YOUR-UUID/flips"

$response = Http::withToken('YOUR_API_KEY')
    ->get("https://watchcron.com/api/v1/checks/{$uuid}/flips");

$flips = $response->json('data');

response = requests.get(
    f"https://watchcron.com/api/v1/checks/{uuid}/flips",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)

flips = response.json()["data"]

const response = await fetch(
  `https://watchcron.com/api/v1/checks/${uuid}/flips`,
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);

const { data: flips } = await response.json();

Response 200 OK

JSON

{
  "data": [
    {
      "old_status": "up",
      "new_status": "grace",
      "created_at": "2026-09-13T14:05:00Z"
    },
    {
      "old_status": "grace",
      "new_status": "down",
      "created_at": "2026-09-13T14:15:00Z"
    },
    {
      "old_status": "down",
      "new_status": "up",
      "created_at": "2026-09-13T14:22:37Z"
    }
  ],
  "meta": {
    "pagination": {
      "total": 12,
      "per_page": 25,
      "current_page": 1,
      "last_page": 1
    }
  }
}

Flip object fields

Field	Type	Description
`old_status`	string	Previous status (`new`, `up`, `grace`, `down`, `paused`)
`new_status`	string	New status after the transition
`created_at`	string	ISO 8601 timestamp of the status change

Flips are useful for calculating uptime, understanding incident timelines, and building custom alerting workflows. A typical down event sequence is: up → grace → down, followed by down → up when the next successful ping arrives.

Sending pings (Ping API)

Ping endpoints are separate from the management API. They require no authentication — just the check UUID or slug in the URL. Both GET and POST methods are accepted (except /log which is POST-only).

Success ping

Report job completed

# Simple GET request — add to the end of your cron job
curl -fsS --retry 3 https://watchcron.com/ping/YOUR-UUID

# Or use POST to include diagnostic data in the body
curl -fsS --retry 3 -X POST \
     --data-raw "Backup completed: 42 tables, 1.2 GB" \
     https://watchcron.com/ping/YOUR-UUID

Start + success pattern (duration tracking)

Track job duration

# Signal that the job has started
curl -fsS --retry 3 https://watchcron.com/ping/YOUR-UUID/start

# ... your job runs ...

# Signal completion — WatchCron calculates the duration
curl -fsS --retry 3 https://watchcron.com/ping/YOUR-UUID

Failure reporting

Report failure

# Report that the job failed — triggers an immediate alert
curl -fsS --retry 3 https://watchcron.com/ping/YOUR-UUID/fail

Log output

Attach log output (POST only)

# Send log output — body is stored (max 100 KB)
curl -fsS --retry 3 -X POST \
     --data-raw "$(cat /var/log/backup.log | tail -100)" \
     https://watchcron.com/ping/YOUR-UUID/log

Complete cron job pattern

The recommended pattern combines start, fail, and success signals:

crontab entry with full monitoring

#!/bin/bash
CHECK_URL="https://watchcron.com/ping/YOUR-UUID"

# Signal start
curl -fsS --retry 3 "${CHECK_URL}/start"

# Run the actual job
if /usr/local/bin/backup.sh; then
    # Success
    curl -fsS --retry 3 "${CHECK_URL}"
else
    # Failure — triggers alert immediately
    curl -fsS --retry 3 "${CHECK_URL}/fail"
fi

Previous ← Checks Next Channels →