Reference

Ping API

The Drumbeats Ping API is one HTTP endpoint per monitor — no SDK, no auth headers. Reference for events, parameters, and response shapes.

The Drumbeats Ping API is the HTTP surface every monitored job calls to report status. One request per ping, no SDK, no authentication header — the monitor ID embedded in the URL is the credential. This page is the reference; see the per-pattern guides below for end-to-end examples.

Base URL

The endpoint takes one of two shapes. Use the project-slug form when you want the same job name to run against multiple Drumbeats projects (staging vs production).

https://api.drumbeats.io/v1/ping/<monitor-id>/<event>

https://api.drumbeats.io/v1/ping/<monitor-id>/<event>

https://api.drumbeats.io/v1/s-ping/<project-id>/<monitor-slug>/<event>

https://api.drumbeats.io/v1/s-ping/<project-id>/<monitor-slug>/<event>

The dashboard's monitor detail page has a URLs panel that copies these ready to paste — avoid UUID typos by copying rather than retyping.

Events

The Ping API accepts four named events plus an exit-code shorthand. Each event sets a different incident behaviour — see Status signals for the decision matrix.

Event	URL suffix	What it means
`start`	`/start`	The job has begun. Optional for Cron monitors, required for Event-driven monitors so duration and hung-run detection work.
`success`	`/success`	The job finished cleanly. Resolves any open incident on the monitor.
`failure`	`/failure`	The job failed. Drumbeats increments the failure counter and opens or extends an incident once `failure_tolerance` is exceeded.
`log`	`/log`	Progress note. Stored on the run timeline, does not change monitor status.
Exit code	`/0`, `/1`, …, `/255`	Shorthand for shell scripts — `0` maps to `success`, any non-zero maps to `failure`. See Exit codes.

HTTP methods

Both GET and POST work for every event. GET is faster and is what most cron-style integrations use. Reach for POST when you need to attach a payload, a run_id, or a manually reported duration_ms.

curl -sf https://api.drumbeats.io/v1/ping/<monitor-id>/success

curl -sf https://api.drumbeats.io/v1/ping/<monitor-id>/success

curl -X POST https://api.drumbeats.io/v1/ping/<monitor-id>/failure \
  -H "Content-Type: application/json" \
  -d '{"run_id": "job-123", "payload": "Connection refused on line 42"}'

curl -X POST https://api.drumbeats.io/v1/ping/<monitor-id>/failure \
  -H "Content-Type: application/json" \
  -d '{"run_id": "job-123", "payload": "Connection refused on line 42"}'

python job.py 2>&1 | curl -X POST https://api.drumbeats.io/v1/ping/<monitor-id>/success \
  -H "Content-Type: text/plain" --data-binary @-

python job.py 2>&1 | curl -X POST https://api.drumbeats.io/v1/ping/<monitor-id>/success \
  -H "Content-Type: text/plain" --data-binary @-

Request parameters

Parameter	Where	Limit	Description
`run_id`	Query string or POST body	255 chars	Correlates the `start`, `log`, and finish pings for one execution. Required for Event-driven monitors.
`payload`	POST body only	Plan dependent (see Payloads)	Stdout, error text, structured JSON — anything that helps triage a failed run.
`duration_ms`	POST body only	—	Manually reported duration in milliseconds. Optional; Drumbeats also infers duration from `start` → finish timing when both pings carry the same `run_id`.

Response shape

A successful ping returns HTTP 200 with this body:

{ "ok": true, "ping_id": "uuid", "timestamp": "2026-05-11T02:00:00.000Z" }

{ "ok": true, "ping_id": "uuid", "timestamp": "2026-05-11T02:00:00.000Z" }

Error responses use standard HTTP status codes:

Status	Meaning
`404`	Monitor not found. Check the monitor ID — copy from the dashboard if unsure.
`429`	Rate limit exceeded. The Ping API allows 600 pings per monitor per minute (~10/sec sustained).
`500`	Server error. Retry with exponential backoff; see Production hardening.

URL examples

Where to go next

Scheduled pings — cron and heartbeat patterns, including duration tracking and the recommended start + success/failure shape.
Event-driven pings — run_id correlation, concurrent workers, queue consumers.
Status signals — when to use named events vs exit-code pings.
Exit codes — the $? shorthand for shell scripts.
Payloads — attaching stdout, structured data, and metrics.
Monitor types — Cron, Heartbeat, Event-driven, Uptime: pick the right one before wiring pings.
Payloads & logs concept — what gets stored, where, and for how long.