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

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




## OpenAPI

````yaml /v3/bundled.yaml post /api/v2/machine-metrics
openapi: 3.0.4
info:
  title: External Service API
  version: 1.0.3
servers:
  - url: https://beaconcha.in
    description: Production API
security:
  - ApiKeyAuth: []
paths:
  /api/v2/machine-metrics:
    post:
      tags:
        - Machine Metrics
      summary: Machine Metrics
      description: >
        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.
      operationId: GetMachineMetrics
      requestBody:
        $ref: '#/components/requestBodies/MachineMetricsRequest'
      responses:
        '200':
          $ref: '#/components/responses/MachineMetrics'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultError'
components:
  requestBodies:
    MachineMetricsRequest:
      x-go-name: MachineMetricsRequestBody
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MachineMetricsRequest'
  responses:
    MachineMetrics:
      description: Successful response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MachineMetrics.Container'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Bad request. Please check your input and try again.
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized. Please provide a valid API key.
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: >-
              endpoint not allowed for your subscription tier. upgrade your
              subscription at https://beaconcha.in/pricing.
    MethodNotAllowed:
      description: Method Not Allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'method not allowed: GET. all public API endpoints use POST.'
    RateLimitExceeded:
      description: Rate Limit Exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Rate limit exceeded. Please try again later.
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: internal server error. please try again later.
    DefaultError:
      description: An unexpected error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: An unexpected error occurred.
  schemas:
    MachineMetricsRequest:
      type: object
      properties:
        machines:
          type: array
          items:
            type: string
          description: >-
            Optional list of machine names to filter by (max 20). If omitted,
            metrics for all machines are returned.
        range:
          $ref: '#/components/schemas/timeRangeSelectorTime'
          description: >
            Time window to query via unix timestamps. Maximum range is 31 days
            (data retention limit).

            Data is returned at per-minute granularity, downsampled for large
            ranges.
        cursor:
          $ref: '#/components/schemas/Cursor'
        page_size:
          $ref: '#/components/schemas/PageSize'
      required:
        - range
    MachineMetrics.Container:
      type: object
      description: >
        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.
      properties:
        data:
          $ref: '#/components/schemas/MachineMetrics.Data'
        paging:
          $ref: '#/components/schemas/Paging'
      required:
        - data
    Error:
      type: object
      properties:
        error:
          type: string
    timeRangeSelectorTime:
      type: object
      title: Unix Timestamp
      description: Range provided via Unix timestamp (inclusive)
      properties:
        timestamp:
          $ref: '#/components/schemas/timeRangeStartEnd'
      required:
        - timestamp
    Cursor:
      type: string
      description: >-
        Cursor value for pagination. See our [pagination guide](/api/pagination)
        for more details.
      default: ''
    PageSize:
      type: integer
      description: The number of items to return per page.
      minimum: 1
      maximum: 10
      default: 10
    MachineMetrics.Data:
      type: object
      properties:
        system_metrics:
          type: array
          description: System metrics ordered by `timestamp DESC`, then `machine ASC`.
          items:
            $ref: '#/components/schemas/MachineMetricSystem'
        validator_metrics:
          type: array
          description: >-
            Validator client metrics ordered by `timestamp DESC`, then `machine
            ASC`.
          items:
            $ref: '#/components/schemas/MachineMetricValidator'
        node_metrics:
          type: array
          description: Beacon node metrics ordered by `timestamp DESC`, then `machine ASC`.
          items:
            $ref: '#/components/schemas/MachineMetricNode'
      required:
        - system_metrics
        - validator_metrics
        - node_metrics
    Paging:
      type: object
      properties:
        next_cursor:
          description: >-
            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.
          type: string
    timeRangeStartEnd:
      type: object
      description: Unix timestamp range (inclusive)
      properties:
        start:
          $ref: '#/components/schemas/timestamp'
          example: 0
          description: Start Unix Timestamp
        end:
          $ref: '#/components/schemas/timestamp'
          example: 2147483647
          description: End Unix Timestamp
      required:
        - start
        - end
    MachineMetricSystem:
      type: object
      properties:
        timestamp:
          $ref: '#/components/schemas/timestamp'
        machine:
          type: string
        exporter_version:
          type: string
        cpu_cores:
          type: integer
        cpu_threads:
          type: integer
        cpu_node_system_seconds_total:
          type: integer
        cpu_node_user_seconds_total:
          type: integer
        cpu_node_iowait_seconds_total:
          type: integer
        cpu_node_idle_seconds_total:
          type: integer
        memory_node_bytes_total:
          type: integer
        memory_node_bytes_free:
          type: integer
        memory_node_bytes_cached:
          type: integer
        memory_node_bytes_buffers:
          type: integer
        disk_node_bytes_total:
          type: integer
        disk_node_bytes_free:
          type: integer
        disk_node_io_seconds:
          type: integer
        disk_node_reads_total:
          type: integer
        disk_node_writes_total:
          type: integer
        network_node_bytes_total_receive:
          type: integer
        network_node_bytes_total_transmit:
          type: integer
        misc_node_boot_ts_seconds:
          type: integer
        misc_os:
          type: string
      required:
        - timestamp
        - machine
    MachineMetricValidator:
      type: object
      properties:
        timestamp:
          $ref: '#/components/schemas/timestamp'
        machine:
          type: string
        exporter_version:
          type: string
        cpu_process_seconds_total:
          type: integer
        memory_process_bytes:
          type: integer
        client_name:
          type: string
        client_version:
          type: string
        client_build:
          type: integer
        sync_eth2_fallback_configured:
          type: boolean
        sync_eth2_fallback_connected:
          type: boolean
        validator_total:
          type: integer
        validator_active:
          type: integer
      required:
        - timestamp
        - machine
    MachineMetricNode:
      type: object
      properties:
        timestamp:
          $ref: '#/components/schemas/timestamp'
        machine:
          type: string
        exporter_version:
          type: string
        cpu_process_seconds_total:
          type: integer
        memory_process_bytes:
          type: integer
        client_name:
          type: string
        client_version:
          type: string
        client_build:
          type: integer
        sync_eth2_fallback_configured:
          type: boolean
        sync_eth2_fallback_connected:
          type: boolean
        disk_beaconchain_bytes_total:
          type: integer
        network_libp2p_bytes_total_receive:
          type: integer
        network_libp2p_bytes_total_transmit:
          type: integer
        network_peers_connected:
          type: integer
        sync_eth1_connected:
          type: boolean
        sync_eth2_synced:
          type: boolean
        sync_beacon_head_slot:
          type: integer
        sync_eth1_fallback_configured:
          type: boolean
        sync_eth1_fallback_connected:
          type: boolean
      required:
        - timestamp
        - machine
    timestamp:
      type: integer
      minimum: 0
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: >-
        Authorization header with value: Bearer YOUR_TOKEN. Refer to the [API
        Keys](/api/overview#api-keys) section to create your API key.

````