> ## 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.

# Machine Metrics

> Push consensus-layer node, validator, and host metrics to your beaconcha.in account

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](https://beaconcha.in/mobile)
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).

<Info>
  For step-by-step client setup (Lighthouse, Prysm, Nimbus, Teku, Lodestar, Rocket Pool),
  follow the [Mobile App Node Monitoring tutorial](/notifications-monitoring/mobile-app-beacon-node).
  This page covers the API contract for direct integrations.
</Info>

## Three payload shapes

Every request carries a `process` field that selects one of three payload
schemas:

| `process`    | What it represents                                     | Sent by               |
| ------------ | ------------------------------------------------------ | --------------------- |
| `system`     | Host machine — CPU, memory, disk, network, OS          | Standalone exporter   |
| `beaconnode` | Consensus-layer client — sync state, peers, libp2p I/O | CL client or exporter |
| `validator`  | Validator client — managed validators, fallback config | VC 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](/api-reference/v1/client/metrics) reference page.
The protobuf source of truth lives at
[`gobitfly/eth2-client-metrics`](https://github.com/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:

```bash theme={null}
# 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](https://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`](https://github.com/gobitfly/eth2-client-metrics-exporter).
It scrapes Prometheus-format metrics from your client and pushes them in the
expected shape:

```bash theme={null}
./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](https://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](https://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](/api-reference/machine-metrics)
endpoint exposes the same underlying data and is the recommended integration
target for new dashboards.

<CardGroup cols={2}>
  <Card title="Endpoint reference" icon="code" href="/api-reference/v1/client/metrics">
    Full request/response schema for `POST /api/v1/client/metrics`.
  </Card>

  <Card title="Setup tutorial" icon="mobile" href="/notifications-monitoring/mobile-app-beacon-node">
    Per-client setup walkthroughs and mobile app login.
  </Card>
</CardGroup>