Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.beaconcha.in/llms.txt

Use this file to discover all available pages before exploring further.

The Machine Metrics endpoint accepts monitoring metrics from your staking infrastructure and stores them against your beaconcha.in account. The data shows up under Machines in the beaconcha.in mobile app and can be used to power alerts and dashboards. It is the same endpoint targeted by the consensus client --monitoring-endpoint flag (Lighthouse, Lodestar, Teku) and by the standalone metrics exporter for clients that don’t expose a push integration natively (Prysm, Nimbus).
For step-by-step client setup (Lighthouse, Prysm, Nimbus, Teku, Lodestar, Rocket Pool), follow the Mobile App Node Monitoring tutorial. This page covers the API contract for direct integrations.

​
Three payload shapes

Every request carries a process field that selects one of three payload schemas:
processWhat it representsSent by
systemHost machine — CPU, memory, disk, network, OSStandalone exporter
beaconnodeConsensus-layer client — sync state, peers, libp2p I/OCL client or exporter
validatorValidator client — managed validators, fallback configVC or exporter
A single request body may be one object or an array of up to 10 objects. Each object is rate-limited to 1 request per user, per machine, per process. The full field-by-field schema is documented on the POST /api/v1/client/metrics reference page. The protobuf source of truth lives at gobitfly/eth2-client-metrics.

​
Two ways to push data

​
1. Native --monitoring-endpoint flag

Lighthouse, Lodestar, and Teku ship with a flag that posts metrics directly to this endpoint. Each client uses a slightly different flag spelling: 
# Lighthouse / Lodestar (validator and beacon node)
--monitoring-endpoint 'https://beaconcha.in/api/v1/client/metrics?apikey=YOUR_API_KEY'

# Teku (beacon node)
--metrics-publish-endpoint 'https://beaconcha.in/api/v1/client/metrics?apikey=YOUR_API_KEY'
Find your API key at beaconcha.in/api/key-management.

​
2. Standalone metrics exporter

For clients without a native flag (Prysm, Nimbus, custom setups), use gobitfly/eth2-client-metrics-exporter. It scrapes Prometheus-format metrics from your client and pushes them in the expected shape: 
./eth2-client-metrics-exporter-linux-amd64 \
  --server.address='https://beaconcha.in/api/v1/client/metrics?apikey=YOUR_API_KEY' \
  --beaconnode.type=prysm \
  --beaconnode.address=http://localhost:8080/metrics \
  --validator.type=prysm \
  --validator.address=http://localhost:8081/metrics
Replace prysm with nimbus, lighthouse, etc. as appropriate for your client. See the exporter README for the full flag reference.

​
Authentication and limits

  • API key: required as the apikey query parameter. Get one at beaconcha.in/api/key-management.
  • Optional machine query parameter: name a device when you monitor more than one host on the same account.
  • Rate limit: 1 request per user per machine per process. Bursts beyond this return 429.
  • Machine count: capped by your subscription tier. Exceeding the cap returns 402. Upgrade at beaconcha.in/pricing.
  • Privacy: beaconcha.in does not store the source IP address of metrics submissions.

​
Reading the data back

The mobile app surfaces this data under Machines. There is no public read endpoint for the V1 API; the V2 POST /api/v2/machine-metrics endpoint exposes the same underlying data and is the recommended integration target for new dashboards.

Endpoint reference

Full request/response schema for POST /api/v1/client/metrics.

Setup tutorial

Per-client setup walkthroughs and mobile app login.