GET /ping

A GET request to /ping/<monitor> is the simplest way to record a monitoring event. It is designed for shell one-liners, cron jobs, IoT devices, healthchecks from routers/NAS appliances, and any environment where setting request headers or building a JSON body is awkward.

Request

GET /ping/<monitor>?status=<state>[&...]

The <monitor> is taken from the URL path. All event fields are query parameters.

Authentication

You can authenticate in two ways. See Authentication for the security tradeoffs.

# Header (recommended for recurring traffic)
curl -H "Authorization: Bearer <api_key>" \
  "https://api.example.com/ping/db-backup?status=complete"

# URL query parameter (convenience — token visible in logs/history/Referer)
curl "https://api.example.com/ping/db-backup?api_key=<api_key>&status=complete"

The Authorization header takes priority. If it is present but malformed or invalid, the request is rejected even when ?api_key= is also provided — no silent fallback.

Query parameters

Param	Type	Required	Description
api_key	string	conditional	API key when not using the Authorization header
status	string	yes	Event status: run, complete, fail, skip
duration	float	no	Execution time in seconds
exit_code	int	no	Process exit code
host	string	no	Hostname that ran the job
msg	string	no	Free-form message / log excerpt (URL-encoded)
series	string	no	Correlation ID grouping run/complete/fail of the same execution

Examples

Job lifecycle (correlated via series)

SERIES=$(uuidgen)
curl "https://api.example.com/ping/db-backup?status=run&series=$SERIES"
# ... job runs ...
curl "https://api.example.com/ping/db-backup?status=complete&series=$SERIES&duration=47.3&exit_code=0"

Failure with message

curl "https://api.example.com/ping/db-backup?status=fail&msg=DB+timeout&exit_code=1"

Skip (maintenance window)

curl "https://api.example.com/ping/payment-service?status=skip"

Crontab one-liner (header auth)

0 3 * * *  /usr/local/bin/pg_dump db > /backups/db.sql && \
  curl -s -H "Authorization: Bearer $API_KEY" \
    "https://api.example.com/ping/db-backup?status=complete" >/dev/null

Response

200 OK

{ "status": "success", "message": "Ping accepted", "monitor": "db-backup", "timestamp": 1779650795 }

400 Bad Request

{ "error": "required field missing: status" }

401 Unauthorized

{ "error": "unauthorized" }

For richer payloads (tags, projects, structured details), use POST /ping with a JSON body.