Ping API reference

Every URL a heartbeat monitor understands: success, start, fail, exit codes, logs.

Every heartbeat monitor has one URL. Append a suffix to say what happened. Any of GET, POST, PUT or HEAD works; the body of a POST or PUT (up to 64 KB, the tail is kept) becomes the run's log.

URL	Meaning
`https://vivere.dev/p/<monitor-id>`	Success. Sets the monitor Up and starts the next period.
`https://vivere.dev/p/<monitor-id>/start`	The job started. Opens a run so the next success or failure records a duration.
`https://vivere.dev/p/<monitor-id>/fail`	The job failed. The monitor goes Down immediately and alerts.
`https://vivere.dev/p/<monitor-id>/<exit-code>`	Report an exit code 0–255. `/0` is success, anything else is a failure with the code recorded.
`https://vivere.dev/p/<monitor-id>/log`	Attach text to the current run without changing status. Useful for progress output.

What a run cost

A success or failure ping can also say what the run used, so an AI agent or an automation can report its model, tokens, cost and how many items it handled. Every value is optional. Put them in the query string:

curl -fsS -m 10 "https://vivere.dev/p/<monitor-id>?model=claude-sonnet-4-5&in=12034&out=1810&cost=0.0631&items=14"

Parameter	Meaning
`model`	The model the run used, up to 100 characters.
`in`, `out`	Input and output tokens.
`cache_read`, `cache_write`	Input tokens read from and written to a prompt cache.
`cost`	What the run cost in US dollars, such as `0.0631`. Kept to a millionth of a dollar.
`items`	How many things the run handled: tickets, rows, emails, files.

Or POST a JSON body with Content-Type: application/json, in the shape claude -p --output-format json prints, so its output can be posted as it is (the AI agents guide shows how):

{
  "model": "claude-sonnet-4-5",
  "usage": {
    "input_tokens": 12034,
    "output_tokens": 1810,
    "cache_read_input_tokens": 40211,
    "cache_creation_input_tokens": 2048
  },
  "total_cost_usd": 0.0631,
  "items": 14
}

Other fields are ignored. Without model, the model that cost most in Claude Code's modelUsage is used. A query parameter wins over the same value in the body. The body is still kept as the run's log.

A value that is not a number, is negative or is out of range (more than 10¹² tokens or items, more than $1,000,000) is dropped and the ping is recorded as usual: usage never makes a ping fail. Start and log pings ignore usage; send it with the ping that ends the run.

The run's page shows what it sent, the monitor's list of runs adds a column for each kind of value any run reported, and the monitor's page totals the cost over the last 30 days. On a heartbeat monitor's settings you can set a cost alert: every run that reports a cost above it alerts the monitor's channels, whether the run succeeded or failed.

Responses

200 OK with the body OK. 404 means the monitor id is unknown or the monitor is an HTTP check. 429 means more than 120 pings a minute for one monitor; slow down.

Timing rules

With a period, the next ping is expected at last success + period, and the deadline is that plus grace.
With a cron expression, the next ping is expected at the next scheduled time after the last success (in the monitor's timezone), plus grace.
Between the expected time and the deadline the monitor shows Late but does not alert.
Past the deadline it is Down and alerts once. The next success sets it Up and sends a recovery alert.
Pinging a paused monitor resumes it.

Safe curl

curl -fsS -m 10 --retry 3 -o /dev/null https://vivere.dev/p/<monitor-id>

-f fails on HTTP errors, -sS is quiet except for errors, -m 10 caps the time, --retry 3 survives a blip.