Docs › Grafana dashboards with RunVouch

Grafana dashboards with RunVouch

Put RunVouch next to the rest of your monitoring: a ready-made dashboard JSON reads RunVouch's public status.json (API uptime, incidents, sealed proof days), an opted-in public fleet (/public/fleet/<slug>.json), and, with your key, your own /v1/agents and /v1/alerts. The package with the dashboard, a README and the datasource settings is at integrations/grafana.

How it runs on Grafana dashboard

Grafana 10 or 11 with the Infinity datasource plugin (or the JSON API datasource; the panels use plain JSON paths, no JSONata). The datasource queries the API from the Grafana server, so browser CORS does not apply.

Store the key

Create the Infinity datasource with an HTTP header X-API-Key holding your RunVouch key (stored encrypted in Grafana). The public endpoints need no key; the /v1/ panels use the datasource header.

Report the run (two HTTP calls)

# endpoints the dashboard reads (GET, JSON)
https://api.runvouch.com/status.json                       # public: uptime windows, incidents, last_heartbeat_age_s, sealed_days
https://api.runvouch.com/public/fleet/<slug>.json          # public, opt-in per account: agents[] with last_run, late, rates, open_alert
https://api.runvouch.com/v1/agents                         # your key: name, state (ok|unproven|failed|alert|running|waiting|paused), cost_24h, last_run
https://api.runvouch.com/v1/alerts                         # your key: open alerts, kind, agent, ts, message

# import
curl -sO https://raw.githubusercontent.com/runvouch/runvouch/main/integrations/grafana/runvouch-dashboard.json
# Grafana: Dashboards, New, Import, upload the file, pick the Infinity datasource, set the fleet slug variable

# the rows the dashboard turns into panels: what an agent reported, checked from outside
rv run nightly-report --evidence-file out/report.html -- python report.py

The start call returns run_id; the end call takes status (ok or fail), optional cost and tokens, and evidence as a JSON object of booleans. Full reference on the API page.

Register the cadence and caps

rv agent nightly-report --cadence 24h --grace 30m --max-runtime 1h --evidence --cap-run-cost 2

Register the agent once, from anywhere with the key. Cadence is what turns a schedule that stopped into an alert; --evidence makes a run without evidence a failure; the caps pause the agent when it overspends.

What goes silent on Grafana dashboard

• A Grafana alert rule on state != ok from /v1/agents is a second, independent pager; RunVouch's own alerts keep going to Telegram, Slack, e-mail, webhook or PagerDuty.
• The public fleet endpoint returns only agents the account owner marked public, and only run facts: no evidence, no cost, no keys. Public fleets are enabled per account; ask with the agents you want listed.
• status.json is about RunVouch itself. If last_heartbeat_age_s climbs past 150, the detector loop is behind and your MISSED alerts are late; the dashboard shows that number on purpose.

What Grafana dashboard does not tell you

Grafana shows what a datasource returns; it does not know an agent was supposed to run at 02:00, or that a green run wrote nothing. That judgment is made in RunVouch (cadence, evidence, caps) and exposed as a state field, which is what the dashboard's stat panels colour on. Grafana alerting on those fields is a useful second channel, not a replacement for the first.

What RunVouch detects

Set up in two minutes

1. Get a free key (3 agents, no card) and store it where this page says.
2. report the run (two http calls): copy the snippet above into the scheduled job.
3. Register the cadence once: rv agent nightly-report --cadence 24h --grace 30m --evidence, or let the first run create the agent and set the cadence on the dashboard.
4. Send one test alert: curl -X POST https://api.runvouch.com/v1/settings/test-alert -H "X-API-Key: $RUNVOUCH_KEY". The next missed, failed or empty run reaches the same channels.

Need a key? Get a free key · Stuck? contact