> ## 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. # 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](https://github.com/gobitfly/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](/api-reference/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, OS * `beaconnode` — consensus-layer client process and sync state * `validator` — 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](https://beaconcha.in/pricing)). See [`gobitfly/eth2-client-metrics`](https://github.com/gobitfly/eth2-client-metrics) for the canonical protobuf specification. ## OpenAPI ````yaml api/v1/bundled.yaml POST /api/v1/client/metrics openapi: 3.0.4 info: title: beaconcha.in API Documentation license: name: GPL-3.0 url: https://www.gnu.org/licenses/gpl-3.0.en.html description: >- > ⚠️ No new features or endpoints will be added to V1. We recommend the [V2 API](/api/overview) for all new projects. See the [migration guide](/api/v1-to-v2-migration). ## Introduction **Advanced and reliable API for accessing comprehensive Ethereum blockchain data.** - **Free Usage Policy:** The API is free to use under a fair use policy, with rate limits of 10 requests per minute per IP. - **Caching:** All responses are cached for 1 minute. - **Higher Usage Plans:** For higher usage plans, visit: [https://beaconcha.in/pricing](https://beaconcha.in/pricing). An API key is required to use these plans. ### API Key Usage API keys can be obtained at [/user/settings](https://beaconcha.in/user/settings) and must be included in requests either as a query string parameter or in the request header. #### Example: Query String Parameter ```bash curl https://beaconcha.in/api/v1/slot/1?apikey= ``` #### Example: Request Header ```bash curl -H 'apikey: ' https://beaconcha.in/api/v1/slot/1 ``` contact: {} version: '1.1' servers: - url: https://beaconcha.in description: Ethereum mainnet - url: https://hoodi.beaconcha.in description: Hoodi Ethereum testnet security: - ApiKeyAuthQuery: [] - ApiKeyAuthHeader: [] tags: - name: Epoch description: Data related to consensus layer epochs - name: Slots description: Data related to consensus layer slots - name: Validators description: Data related to consensus layer validators - name: Rewards description: Data related to validator rewards - name: Sync Committees description: Data related to sync committees - name: Rocketpool description: Data related to the rocketpool protocol - name: ETH.Store® description: Data related to the ETH.Store® metric - name: Validator deposits description: Data related to execution layer validator deposits - name: Blocks description: Data related to execution layer blocks - name: Gas description: Data related to gas prices - name: Address description: Data related to ethereum addresses - name: Network description: Network data - name: Misc description: Miscellaneous data - name: User description: User data - name: Machine Metrics description: Submit machine, beacon-node, and validator-client monitoring metrics paths: /api/v1/client/metrics: post: tags: - Machine Metrics summary: Submit machine metrics description: >- 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](https://github.com/gobitfly/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](/api-reference/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, OS * `beaconnode` — consensus-layer client process and sync state * `validator` — 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](https://beaconcha.in/pricing)). See [`gobitfly/eth2-client-metrics`](https://github.com/gobitfly/eth2-client-metrics) for the canonical protobuf specification. operationId: postClientMetricsV1 parameters: - name: apikey in: query description: User API key. Find it at https://beaconcha.in/api/key-management. required: true schema: type: string - name: machine in: query description: >- 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. required: false schema: type: string requestBody: description: A single metrics object or an array of up to 10 metrics objects. required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/types.MachineMetricsBody' - type: array maxItems: 10 items: $ref: '#/components/schemas/types.MachineMetricsBody' examples: system: summary: System metrics (process=system) value: 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 beaconnode: summary: Beacon-node metrics (process=beaconnode) value: version: 2 timestamp: 1714500000 process: beaconnode exporter_version: 1.0.0 cpu_process_seconds_total: 4321 memory_process_bytes: 1500000000 client_name: prysm client_version: 5.0.0 client_build: 1 sync_eth2_fallback_configured: false sync_eth2_fallback_connected: false disk_beaconchain_bytes_total: 80000000000 network_libp2p_bytes_total_receive: 1234567 network_libp2p_bytes_total_transmit: 7654321 network_peers_connected: 80 sync_eth1_connected: true sync_eth2_synced: true sync_beacon_head_slot: 9000000 sync_eth1_fallback_configured: false sync_eth1_fallback_connected: false validator: summary: Validator-client metrics (process=validator) value: version: 2 timestamp: 1714500000 process: validator exporter_version: 1.0.0 cpu_process_seconds_total: 1234 memory_process_bytes: 500000000 client_name: prysm client_version: 5.0.0 client_build: 1 sync_eth2_fallback_configured: false sync_eth2_fallback_connected: false validator_total: 32 validator_active: 32 batch: summary: Batch — multiple processes for one host in one request value: - version: 2 timestamp: 1714500000 process: system exporter_version: 1.0.0 cpu_cores: 8 - version: 2 timestamp: 1714500000 process: beaconnode exporter_version: 1.0.0 client_name: prysm sync_eth2_synced: true - version: 2 timestamp: 1714500000 process: validator exporter_version: 1.0.0 client_name: prysm validator_active: 32 responses: '200': description: >- Metrics accepted and stored. Response body is the standard `ApiResponse` envelope with `status: OK` and a null `data` field. content: application/json: schema: $ref: '#/components/schemas/types.ApiResponse' '400': description: >- The request is invalid — examples include a malformed JSON body, an unknown `process` value, an unsupported `version`, or an array with more than 10 entries. content: application/json: schema: $ref: '#/components/schemas/types.ApiErrorResponse' examples: invalidJson: summary: Invalid JSON value: status: 'ERROR: Invalid JSON format in request body' data: null unknownProcess: summary: Unknown process value value: status: 'ERROR: unknown process' data: null unsupportedVersion: summary: Unsupported version value: status: 'ERROR: this version is not supported' data: null tooManyEntries: summary: Array too large value: status: 'ERROR: Max number of stat entries are 10' data: null badApiKey: summary: API key not recognized value: status: 'ERROR: no user found with api key' data: null '402': description: >- Reached the maximum number of distinct machines allowed for your subscription tier. Upgrade at https://beaconcha.in/pricing. content: application/json: schema: $ref: '#/components/schemas/types.ApiErrorResponse' examples: maxMachines: summary: Max machine count reached value: status: 'ERROR: reached max machine count' data: null '429': description: >- Rate limit exceeded. Submissions are limited to 1 request per user, per machine, per process. content: application/json: schema: $ref: '#/components/schemas/types.ApiErrorResponse' examples: rateLimited: summary: Rate limited value: status: >- ERROR: rate limit too many metric requests, max 1 per user per machine per process data: null '500': description: An unexpected server error occurred. content: application/json: schema: $ref: '#/components/schemas/types.ApiErrorResponse' components: schemas: types.MachineMetricsBody: description: >- A single machine-metrics submission. The `process` discriminator selects between the three payload variants: `system`, `beaconnode`, and `validator`. oneOf: - $ref: '#/components/schemas/types.MachineMetricSystem' - $ref: '#/components/schemas/types.MachineMetricBeaconNode' - $ref: '#/components/schemas/types.MachineMetricValidator' discriminator: propertyName: process mapping: system: $ref: '#/components/schemas/types.MachineMetricSystem' beaconnode: $ref: '#/components/schemas/types.MachineMetricBeaconNode' validator: $ref: '#/components/schemas/types.MachineMetricValidator' types.ApiResponse: type: object description: Standard success envelope used by all API endpoints. properties: status: type: string description: >- HTTP-independent status of the API operation. For successful responses this is always "OK". enum: - OK data: description: Response payload specific to the endpoint. nullable: true x-omitempty: true types.ApiErrorResponse: type: object description: Standard error envelope returned when a request fails. properties: status: type: string description: >- Human-readable error indicator and message. The value begins with "ERROR:" followed by details. example: 'ERROR: ' data: type: string description: Optional additional context for the error. Null in most cases. nullable: true default: null types.MachineMetricSystem: description: Host-system metrics. `process` must be `system`. allOf: - $ref: '#/components/schemas/types.MachineMetricsMeta' - type: object properties: cpu_cores: type: integer description: Total physical CPU cores. cpu_threads: type: integer description: Total CPU threads (hardware threads / vCPUs). cpu_node_system_seconds_total: type: integer description: Cumulative CPU seconds spent in kernel mode. cpu_node_user_seconds_total: type: integer description: Cumulative CPU seconds spent in user mode. cpu_node_iowait_seconds_total: type: integer description: Cumulative CPU seconds spent waiting on I/O. cpu_node_idle_seconds_total: type: integer description: Cumulative CPU seconds spent idle. memory_node_bytes_total: type: integer description: Total system memory in bytes. memory_node_bytes_free: type: integer description: Free system memory in bytes. memory_node_bytes_cached: type: integer description: Cached memory in bytes. memory_node_bytes_buffers: type: integer description: Memory used as kernel buffers in bytes. disk_node_bytes_total: type: integer description: Total disk capacity in bytes. disk_node_bytes_free: type: integer description: Free disk space in bytes. disk_node_io_seconds: type: integer description: Cumulative time the disk spent on I/O, in seconds. disk_node_reads_total: type: integer description: Cumulative number of disk reads. disk_node_writes_total: type: integer description: Cumulative number of disk writes. network_node_bytes_total_receive: type: integer description: Cumulative bytes received on the network interface. network_node_bytes_total_transmit: type: integer description: Cumulative bytes transmitted on the network interface. misc_node_boot_ts_seconds: type: integer description: Unix timestamp (seconds) at which the host last booted. misc_os: type: string description: Operating-system identifier (e.g., `linux`). types.MachineMetricBeaconNode: description: >- Beacon-node (consensus-layer client) metrics. `process` must be `beaconnode`. allOf: - $ref: '#/components/schemas/types.MachineMetricsMeta' - type: object properties: cpu_process_seconds_total: type: integer description: Cumulative CPU seconds consumed by the beacon-node process. memory_process_bytes: type: integer description: Resident memory used by the beacon-node process, in bytes. client_name: type: string description: >- Client implementation (e.g., `lighthouse`, `prysm`, `nimbus`, `teku`, `lodestar`). client_version: type: string description: Client version string. client_build: type: integer description: Client build identifier. sync_eth2_fallback_configured: type: boolean description: Whether a fallback consensus-layer endpoint is configured. sync_eth2_fallback_connected: type: boolean description: Whether the configured CL fallback is currently connected. disk_beaconchain_bytes_total: type: integer description: Bytes used on disk by the beacon-chain database. network_libp2p_bytes_total_receive: type: integer description: Cumulative bytes received over libp2p. network_libp2p_bytes_total_transmit: type: integer description: Cumulative bytes transmitted over libp2p. network_peers_connected: type: integer description: Number of currently connected libp2p peers. sync_eth1_connected: type: boolean description: Whether the execution-layer endpoint is reachable. sync_eth2_synced: type: boolean description: Whether the beacon node is synced to head. sync_beacon_head_slot: type: integer description: Current head slot known to the beacon node. sync_eth1_fallback_configured: type: boolean description: Whether a fallback execution-layer endpoint is configured. sync_eth1_fallback_connected: type: boolean description: Whether the configured EL fallback is currently connected. types.MachineMetricValidator: description: Validator-client metrics. `process` must be `validator`. allOf: - $ref: '#/components/schemas/types.MachineMetricsMeta' - type: object properties: cpu_process_seconds_total: type: integer description: Cumulative CPU seconds consumed by the validator-client process. memory_process_bytes: type: integer description: Resident memory used by the validator-client process, in bytes. client_name: type: string description: Validator-client implementation (e.g., `lighthouse`, `prysm`). client_version: type: string description: Client version string. client_build: type: integer description: Client build identifier. sync_eth2_fallback_configured: type: boolean description: Whether a fallback CL endpoint is configured for the VC. sync_eth2_fallback_connected: type: boolean description: Whether the configured CL fallback is currently connected. validator_total: type: integer description: Total number of validator keys managed by this client. validator_active: type: integer description: Number of managed validators currently in the active set. types.MachineMetricsMeta: type: object description: Envelope fields shared by all three machine-metrics payload variants. required: - version - timestamp - process properties: version: type: integer enum: - 1 - 2 description: Payload schema version. Currently 1 or 2. timestamp: type: integer format: int64 description: Unix timestamp (seconds) at which the snapshot was taken. process: type: string enum: - system - beaconnode - validator description: Discriminator selecting the payload variant. exporter_version: type: string description: Version string of the exporter that produced the metrics. securitySchemes: ApiKeyAuthQuery: type: apiKey in: query name: apikey description: '' ApiKeyAuthHeader: type: apiKey in: header name: apikey description: '' ````