Introduction
V1 API Docs
Legacycurl --request POST \
--url 'https://beaconcha.in/api/v1/client/metrics?apikey=' \
--header 'Content-Type: application/json' \
--data '
{
"version": 2,
"timestamp": 1714500000,
"process": "system",
"exporter_version": "1.0.0",
"cpu_cores": 8,
"cpu_threads": 16,
"cpu_node_system_seconds_total": 12345,
"cpu_node_user_seconds_total": 67890,
"cpu_node_iowait_seconds_total": 100,
"cpu_node_idle_seconds_total": 543210,
"memory_node_bytes_total": 33285996544,
"memory_node_bytes_free": 8200000000,
"memory_node_bytes_cached": 12000000000,
"memory_node_bytes_buffers": 500000000,
"disk_node_bytes_total": 2000000000000,
"disk_node_bytes_free": 1500000000000,
"disk_node_io_seconds": 200,
"disk_node_reads_total": 1000000,
"disk_node_writes_total": 500000,
"network_node_bytes_total_receive": 9876543210,
"network_node_bytes_total_transmit": 1234567890,
"misc_node_boot_ts_seconds": 1714000000,
"misc_os": "linux"
}
'{
"status": "OK",
"data": "<unknown>"
}Submit Machine Metrics
Submits monitoring metrics from a consensus-layer client, validator client, or host machine to the authenticated beaconcha.in account. The endpoint is the target of the consensus-client --monitoring-endpoint flag (Lighthouse, Lodestar, Teku) and of the standalone eth2-client-metrics-exporter. Submitted data appears in the Machines view of the beaconcha.in mobile app and can be read back via POST /api/v2/machine-metrics.
The request body is either a single metrics object or an array of up to 10 objects. Each object must include a process discriminator that selects one of three payload schemas:
system— host CPU, memory, disk, network, OSbeaconnode— consensus-layer client process and sync statevalidator— validator-client process and managed-validator counts
Submissions are rate-limited to 1 request per user per machine per process. The maximum number of distinct machines is determined by your subscription tier (see pricing).
See gobitfly/eth2-client-metrics for the canonical protobuf specification.
curl --request POST \
--url 'https://beaconcha.in/api/v1/client/metrics?apikey=' \
--header 'Content-Type: application/json' \
--data '
{
"version": 2,
"timestamp": 1714500000,
"process": "system",
"exporter_version": "1.0.0",
"cpu_cores": 8,
"cpu_threads": 16,
"cpu_node_system_seconds_total": 12345,
"cpu_node_user_seconds_total": 67890,
"cpu_node_iowait_seconds_total": 100,
"cpu_node_idle_seconds_total": 543210,
"memory_node_bytes_total": 33285996544,
"memory_node_bytes_free": 8200000000,
"memory_node_bytes_cached": 12000000000,
"memory_node_bytes_buffers": 500000000,
"disk_node_bytes_total": 2000000000000,
"disk_node_bytes_free": 1500000000000,
"disk_node_io_seconds": 200,
"disk_node_reads_total": 1000000,
"disk_node_writes_total": 500000,
"network_node_bytes_total_receive": 9876543210,
"network_node_bytes_total_transmit": 1234567890,
"misc_node_boot_ts_seconds": 1714000000,
"misc_os": "linux"
}
'{
"status": "OK",
"data": "<unknown>"
}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.
Authorizations
Query Parameters
User API key. Find it at https://beaconcha.in/api/key-management.
Optional name to distinguish multiple devices on the same account. Use the same name across the validator-client, beacon-node, and system-metrics submissions for one host.
Body
A single metrics object or an array of up to 10 metrics objects.
A single machine-metrics submission. The process discriminator selects between the three payload variants: system, beaconnode, and validator.
Payload schema version. Currently 1 or 2.
1, 2 Unix timestamp (seconds) at which the snapshot was taken.
Discriminator selecting the payload variant.
system, beaconnode, validator Version string of the exporter that produced the metrics.
Total physical CPU cores.
Total CPU threads (hardware threads / vCPUs).
Cumulative CPU seconds spent in kernel mode.
Cumulative CPU seconds spent in user mode.
Cumulative CPU seconds spent waiting on I/O.
Cumulative CPU seconds spent idle.
Total system memory in bytes.
Free system memory in bytes.
Cached memory in bytes.
Memory used as kernel buffers in bytes.
Total disk capacity in bytes.
Free disk space in bytes.
Cumulative time the disk spent on I/O, in seconds.
Cumulative number of disk reads.
Cumulative number of disk writes.
Cumulative bytes received on the network interface.
Cumulative bytes transmitted on the network interface.
Unix timestamp (seconds) at which the host last booted.
Operating-system identifier (e.g., linux).
Response
Metrics accepted and stored. Response body is the standard ApiResponse envelope with status: OK and a null data field.
Was this page helpful?