---
title: "Machine Metrics"
method: POST
path: "/api/v2/machine-metrics"
tags: ["Machine Metrics"]
---

# Machine Metrics

`POST /api/v2/machine-metrics`

Retrieve machine monitoring metrics for the authenticated user. Returns system, validator client, and beacon node metrics
that were previously pushed via the `--monitoring-endpoint` flag and set up via https://beaconcha.in/user/settings#app.

Users can only access metrics belonging to their own API key. Optionally filter by one or more machine names.

Provide a time range via unix timestamps to query a specific historical window (maximum 31 days, limited by data retention).
Each array is ordered newest first, then paginated toward older data.

Pagination uses an opaque continuation token that tracks the last emitted `(timestamp, machine)` tuple separately for
`system_metrics`, `validator_metrics`, and `node_metrics`. Clients must treat `paging.next_cursor` as opaque.

## Request body

- MachineMetricsRequest
  - `machines` string[] — Optional list of machine names to filter by (max 20). If omitted, metrics for all machines are returned.
  - `range` TimeRangeSelectorTime, required — Range provided via Unix timestamp (inclusive)
    - `timestamp` TimeRangeStartEnd, required — Unix timestamp range (inclusive)
      - `start` integer, required
      - `end` integer, required
  - `cursor` string — Cursor value for pagination. See our [pagination guide](/api/pagination) for more details.
  - `page_size` integer — The number of items to return per page.

## Response `200`

Successful response.

- MachineMetricsContainer — Machine metrics grouped into `system_metrics`, `validator_metrics`, and `node_metrics` arrays. Each array is independently ordered by `timestamp DESC`, then `machine ASC`, and paginated toward older data.
  - `data` MachineMetricsData, required
    - `system_metrics` MachineMetricSystem[], required — System metrics ordered by `timestamp DESC`, then `machine ASC`.
      - `timestamp` integer, required
      - `machine` string, required
      - `exporter_version` string
      - `cpu_cores` integer
      - `cpu_threads` integer
      - `cpu_node_system_seconds_total` integer
      - `cpu_node_user_seconds_total` integer
      - `cpu_node_iowait_seconds_total` integer
      - `cpu_node_idle_seconds_total` integer
      - `memory_node_bytes_total` integer
      - `memory_node_bytes_free` integer
      - `memory_node_bytes_cached` integer
      - `memory_node_bytes_buffers` integer
      - `disk_node_bytes_total` integer
      - `disk_node_bytes_free` integer
      - `disk_node_io_seconds` integer
      - `disk_node_reads_total` integer
      - `disk_node_writes_total` integer
      - `network_node_bytes_total_receive` integer
      - `network_node_bytes_total_transmit` integer
      - `misc_node_boot_ts_seconds` integer
      - `misc_os` string
    - `validator_metrics` MachineMetricValidator[], required — Validator client metrics ordered by `timestamp DESC`, then `machine ASC`.
      - `timestamp` integer, required
      - `machine` string, required
      - `exporter_version` string
      - `cpu_process_seconds_total` integer
      - `memory_process_bytes` integer
      - `client_name` string
      - `client_version` string
      - `client_build` integer
      - `sync_eth2_fallback_configured` boolean
      - `sync_eth2_fallback_connected` boolean
      - `validator_total` integer
      - `validator_active` integer
    - `node_metrics` MachineMetricNode[], required — Beacon node metrics ordered by `timestamp DESC`, then `machine ASC`.
      - `timestamp` integer, required
      - `machine` string, required
      - `exporter_version` string
      - `cpu_process_seconds_total` integer
      - `memory_process_bytes` integer
      - `client_name` string
      - `client_version` string
      - `client_build` integer
      - `sync_eth2_fallback_configured` boolean
      - `sync_eth2_fallback_connected` boolean
      - `disk_beaconchain_bytes_total` integer
      - `network_libp2p_bytes_total_receive` integer
      - `network_libp2p_bytes_total_transmit` integer
      - `network_peers_connected` integer
      - `sync_eth1_connected` boolean
      - `sync_eth2_synced` boolean
      - `sync_beacon_head_slot` integer
      - `sync_eth1_fallback_configured` boolean
      - `sync_eth1_fallback_connected` boolean
  - `paging` Paging
    - `next_cursor` string — Cursor to the next page of results. See our [pagination guide](/api/pagination) for more details. If empty, there are no more pages to fetch.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `405` — Method Not Allowed
- `429` — Rate Limit Exceeded
- `500` — Internal Server Error
- `default` — An unexpected error response.

---

[API](https://skmtc.dev/beaconcha/apis/external-service-api.md) · [All operations](https://skmtc.dev/beaconcha/apis/external-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/beaconcha/external-service-api/revisions/ad26ad970b4e/schema)