Ping API

Overview

The Ping API is how your cron jobs and scripts report their status to Cronping. No authentication is required — the unique token in the URL acts as the credential.

Base URL:

https://ping.cronping.com/<token>

Cronping accepts GET, POST, and HEAD requests for maximum compatibility with any HTTP client or scripting environment.

Endpoints

All endpoints accept an optional ?rid=<uuid> query parameter to correlate start/end pings for concurrent job executions.

Success ping

Send a ping to signal that your job completed successfully. This sets the heartbeat status to Up and resets the deadline for the next expected ping.

GET https://ping.cronping.com/<token>

If a /start ping was previously received, the response includes durationMs — the time between start and success in milliseconds.

Response

{
  "ok": true,
  "status": "up",
  "nextExpectedAt": "2024-01-15T04:00:00.000Z",
  "durationMs": 4523
}

Start ping

Send before the job begins. Cronping records the start time and shows a "Running" indicator in the dashboard. If no success or fail ping arrives within the grace period, Cronping marks the heartbeat as Down and triggers alerts.

GET https://ping.cronping.com/<token>/start

Response

{
  "ok": true,
  "status": "started"
}

Use case: measure script run time

#!/bin/sh
curl -fsS -m 10 https://ping.cronping.com/<token>/start
/usr/bin/backup.sh
curl -fsS -m 10 https://ping.cronping.com/<token>

Cronping will automatically calculate the duration between the start and success pings and display it in the ping history.

Fail ping

Send to immediately signal failure. This sets the heartbeat status to Down and triggers alerts right away — without waiting for the grace period to expire.

GET https://ping.cronping.com/<token>/fail

Response

{
  "ok": true,
  "status": "down"
}

Use case: report failure on error

#!/bin/sh
/usr/bin/backup.sh
if [ $? -ne 0 ]; then
  curl -fsS -m 10 https://ping.cronping.com/<token>/fail
else
  curl -fsS -m 10 https://ping.cronping.com/<token>
fi

Exit code ping

Append the shell exit code (0–255) to the ping URL. Exit code 0 is treated as success; any other value is treated as failure.

GET https://ping.cronping.com/<token>/<exit-code>

This is the simplest way to wrap any script — just pass $?:

#!/bin/sh
/usr/bin/backup.sh
curl -fsS -m 10 https://ping.cronping.com/<token>/$?

The exit code is recorded in the ping history for debugging.

Log ping

Send a log entry without changing the heartbeat status. Useful for attaching diagnostic output mid-job.

POST https://ping.cronping.com/<token>/log

Response

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

The response status reflects whatever the heartbeat's current status is — the /log endpoint never changes it.

Run ID (?rid=)

When running multiple instances of the same job concurrently, attach a unique run ID to correlate start and end pings:

RID=$(uuidgen)
curl -fsS -m 10 "https://ping.cronping.com/<token>/start?rid=$RID"
/usr/bin/backup.sh
curl -fsS -m 10 "https://ping.cronping.com/<token>/$??rid=$RID"

The run ID is stored in the ping history, making it easy to group events by job execution in the dashboard.

Status codes

Paused heartbeats

If the heartbeat is paused, any ping type is accepted silently — no state change occurs.

Slug URLs

As an alternative to token-based URLs, you can use slug URLs that are human-readable and safe to commit to version control:

https://ping.cronping.com/<ping-key>/<slug>

The ping-key is a per-organization secret (generated in Organization Settings), and the slug is a human-readable identifier set on each heartbeat (e.g., db-backup, cache-warm).

Slug URLs support all the same actions: /start, /fail, /log, /{exit-code}, and ?rid=.

Add ?create=1 to auto-create a heartbeat on first ping — no dashboard setup needed. The response returns 201 with "created": true. See Auto-provisioning for details.

See the Slug URLs guide for setup instructions and examples.

{
  "ok": true,
  "status": "paused"
}

Request methods

Quick examples

curl (success)

curl -fsS https://ping.cronping.com/<token>

curl with timeout

curl -fsS --max-time 10 https://ping.cronping.com/<token>

Full script with start + exit code

#!/bin/sh
curl -fsS -m 10 https://ping.cronping.com/<token>/start
/usr/bin/backup.sh
curl -fsS -m 10 https://ping.cronping.com/<token>/$?

wget

wget -q -O /dev/null https://ping.cronping.com/<token>

PowerShell

Invoke-RestMethod -Uri "https://ping.cronping.com/<token>"

Error handling

If the curl command fails (e.g. network error, 404), it will exit with a non-zero code. In a cron job, this is usually fine — the job has already succeeded. However, if you want to catch ping errors, you can redirect or check the exit code:

0 3 * * * /usr/bin/backup.sh && \
  curl -fsS --max-time 10 https://ping.cronping.com/<token> \
  || echo "Cronping unreachable" >> /var/log/backup.log

Request body

All ping endpoints accept an optional request body via POST. The body is stored alongside the ping event and can serve two purposes:

Log context in alerts

When an alert fires, Cronping attaches the most recent ping body as a log excerpt in the notification. This means your team sees the job output directly in the alert — no need to SSH in.

OUTPUT=$(/usr/bin/backup.sh 2>&1)
curl -fsS -m 10 https://ping.cronping.com/<token>/$? \
  -X POST --data-raw "$OUTPUT"

The body is truncated to 100 KB at ingestion. Log excerpts in alerts are further capped at 50 lines / 10 KB.

JSON payloads + alert rules

If the body is valid JSON and the heartbeat has alert rules configured, Cronping evaluates those rules against the payload fields. A success ping can be automatically turned into a failure if the data indicates a problem.

curl -fsS -m 10 https://ping.cronping.com/<token> \
  -d '{"rows_processed": 0, "status": "ok"}'

With a rule rows_processed < 1 → fail, this ping would be treated as a failure despite the success endpoint.

See Alert Rules for full documentation.

Recovery alerts

When Cronping receives a success ping for a heartbeat that was previously Down, it sends a recovery alert to all configured integrations. You do not need to do anything special — this happens automatically.