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

# Introduction

> Monitor validator performance using BeaconScore and the Performance API

## Overview

BeaconScore is a transparent, comprehensive metric that measures how well your validators perform their duties. It combines attestations, block proposals, and sync committee participation into a single score.

<Note>
  **API Endpoints:** This guide covers [`/api/v2/ethereum/validators/performance-aggregate`](/api-reference/ethereum/validators/performance-aggregate) for summary metrics and [`/api/v2/ethereum/validators/performance-list`](/api-reference/ethereum/validators/performance-list) for per-epoch breakdowns.
</Note>

<Info>
  BeaconScore is designed to normalize for luck—validators with fewer block proposals aren't unfairly penalized. This makes it ideal for comparing performance across different validators, nodes, or client configurations. Note that some [residual luck factors](/validator-dashboard/metric-validator-efficiency#residual-luck-factors) outside a validator's control can still influence the score, especially over short evaluation windows.
</Info>

***

## Why Monitor Performance?

<CardGroup cols={2}>
  <Card title="Identify Issues Early" icon="triangle-exclamation">
    Spot underperforming validators before they significantly impact your rewards.
  </Card>

  <Card title="Compare Configurations" icon="code-compare">
    Evaluate different client software, hardware setups, or network configurations.
  </Card>

  <Card title="Client Reporting" icon="file-chart-column">
    Provide transparent performance metrics to your staking customers.
  </Card>

  <Card title="Optimize Operations" icon="gauge-high">
    Track improvements over time and validate infrastructure changes.
  </Card>
</CardGroup>

***

## BeaconScore Components

BeaconScore integrates three components weighted by their contribution to validator rewards:

| Component           | Weight | Description                                                                                                                                       |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Attestations**    | 84.4%  | Head, source, and target votes each epoch (\~6.4 min)                                                                                             |
| **Block Proposals** | 12.5%  | CL rewards from proposed blocks (luck-normalized; see [residual factors](/validator-dashboard/metric-validator-efficiency#residual-luck-factors)) |
| **Sync Committees** | 3.1%   | Participation when elected to sync committee                                                                                                      |

<Note>
  Learn more about how each component is calculated in [BeaconScore](/beaconscore/introduction).
</Note>

***

## Benchmark Values

| BeaconScore   | Rating    | Action                        |
| ------------- | --------- | ----------------------------- |
| ≥ 99.5%       | Excellent | Optimal performance           |
| 99.0% - 99.5% | Good      | Within acceptable range       |
| 98.0% - 99.0% | Fair      | Minor issues, monitor closely |
| \< 98.0%      | Poor      | Investigate immediately       |

***

## Quick Start: Check Your Performance

Get the aggregated BeaconScore for your validators over the last 30 days:

```bash theme={null}
curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/validators/performance-aggregate \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chain": "mainnet",
  "validator": {
    "dashboard_id": 123
  },
  "range": {
    "evaluation_window": "30d"
  }
}
'
```

### Response

```json theme={null}
{
  "data": {
    "beaconscore": {
      "total": 0.9945,
      "attestation": 0.9952,
      "proposal": 0.9876,
      "sync_committee": 0.9991
    },
    "duties": {
      "attestation": {
        "included": 7983797,
        "assigned": 7985250,
        "missed": 1453
      },
      "proposal": {
        "successful": 229,
        "assigned": 231,
        "missed": 2
      },
      "sync_committee": {
        "successful": 134833,
        "assigned": 135818,
        "missed": 985
      }
    }
  },
  "range": {
    "epoch": { "start": 407453, "end": 414202 }
  }
}
```

***

## Per-Epoch Performance History

For detailed analysis, query performance for specific epochs:

```bash theme={null}
curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/validators/performance-list \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chain": "mainnet",
  "validator": {
    "validator_identifiers": [1, 2, 3]
  },
  "epoch": 413950,
  "page_size": 100
}
'
```

<Note>
  The `epoch` parameter is required for the performance-list endpoint. Use this to investigate specific time periods or track performance over time.
</Note>

***

## Choose an Evaluation Window

Use the same window for every value in a comparison. Available windows are `24h`, `7d`, `30d`, `90d`, and `all_time`. See the [Performance Aggregate API reference](/api-reference/ethereum/validators/performance-aggregate).

On [Scale and Enterprise plans](https://beaconcha.in/pricing) you can also pass a custom `timestamp`, `epoch`, or `slot` range instead of a named window. Custom ranges are served at whole-UTC-day granularity, and the response `range` echoes the actual covered range.

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Use 30-Day Windows" icon="calendar">
    Short windows are noisy due to [luck](/validator-dashboard/metric-validator-efficiency#residual-luck-factors). Use 30d or longer for meaningful comparisons.
  </Card>

  <Card title="Group by Infrastructure" icon="server">
    Create dashboard groups for each node, client, or geographic location.
  </Card>

  <Card title="Set Alerts" icon="bell">
    Configure [notifications](/notifications-monitoring/notifications) for performance drops.
  </Card>

  <Card title="Regular Reviews" icon="chart-line">
    Schedule weekly or monthly performance reviews to catch gradual degradation.
  </Card>
</CardGroup>

***

## Deep Dive Guides

<CardGroup cols={2}>
  <Card title="Analyze Missed Rewards" icon="chart-pie" href="/use-cases/missed-rewards">
    Per-epoch breakdown of rewards lost due to missed duties. Diagnose issues by duty type (attestations, proposals, sync).
  </Card>

  <Card title="APY & ROI Metrics" icon="percent" href="/use-cases/apy-roi">
    Aggregated return metrics with EL/CL breakdown. Includes missed reward impact on overall APY.
  </Card>

  <Card title="Embed BeaconScore" icon="code" href="/use-cases/embed-beaconscore">
    Integrate BeaconScore into your product with attribution guidelines.
  </Card>
</CardGroup>

***

## Related Resources

* [BeaconScore Calculation](/beaconscore/introduction) — Deep dive into the formula
* [Dashboard as Private Sets](/use-cases/rewards-dashboard-private-sets) — Organize validators into groups
* [Notifications](/notifications-monitoring/notifications) — Set up performance alerts

<Tip>
  API references: [Performance Aggregated](/api-reference/ethereum/validators/performance-aggregate) and [Performance List](/api-reference/ethereum/validators/performance-list).
</Tip>