---
title: "Performance Aggregated"
method: POST
path: "/api/v2/ethereum/validators/performance-aggregate"
tags: ["Performance"]
---

# Performance Aggregated

`POST /api/v2/ethereum/validators/performance-aggregate`

Returns aggregated performance metrics for a known collection or group of validators. Known collections are referenced by index, public key, deposit address, or withdrawal address.

**Use case guide:** [Validator performance](/use-cases/performance-introduction) explains how to monitor BeaconScore, select evaluation windows, and compare validator sets.

This endpoint includes the **BeaconScore** metric, which measures how well validators perform their duties. Learn more about [how BeaconScore is calculated](/beaconscore/introduction).

**Coming Soon:** Support for querying arbitrary time ranges using Unix timestamps, epochs, or slots — exclusively for [Scale and Enterprise plans](https://beaconcha.in/pricing).

## Request body

- AggregateValidatorChainStartEnd
  - `chain` 'mainnet' | 'hoodi' — The Ethereum chain to query.
  - `validator` union, required — Free selectors available to all users: - validator_identifiers: One or more validator indices or public keys to filter by. - dashboard_id: Your beaconcha.in dashboard ID (requires a free account). **Premium selectors** for Scale & Enterprise plans (https://beaconcha.in/pricing): - withdrawal: The validator's withdrawal credential or the Ethereum wallet address used for withdrawals. - deposit_address: The Ethereum wallet address used for the validator's deposit. - entity: The name of the assigned entity (e.g., "Lido", "Coinbase"). Optionally include `sub_entity` for more specific filtering. Matching is case-sensitive. Note: The set of validators matched by `deposit_address` and `withdrawal` selectors is updated once per epoch (~6.4 minutes). Newly deposited validators may take up to one epoch to appear in query results. Note: The set of validators matched by `entity` selector is updated once per day.
    - ValidatorsByIdentifiers
      - `validator_identifiers` ValidatorIndexPublicKey[], required — An array containing either validator indices or public keys. Index and public key can be mixed in the same array. Subscribed users (Hobbyist, Business, and Scale tiers) can include up to 100 entries; free trial users and legacy subscription users (Sapphire, Emerald, Diamond) are limited to 20.
        - union
          - integer — Validator Index
          - string — Public key of a validator
    - ValidatorsByDashboard
      - `dashboard_id` integer, required — beaconcha.in dashboard ID. You can find your dashboard ID in the URL of your dashboard page on beaconcha.in (e.g., https://beaconcha.in/dashboard/12345).
      - `group_id` integer, nullable — Optional beaconcha.in dashboard group ID. If no group ID is provided, all validators in the dashboard are considered.
    - ValidatorsByDeposit
      - `deposit_address` string, required — A standard Ethereum address (20-byte hex string with 0x prefix).
    - ValidatorsByWithdrawal
      - `withdrawal` string, required — Either an execution layer address (20-byte hex string with 0x prefix) or a full 32-byte withdrawal credential.
    - ValidatorsByEntity — Select validators by their assigned entity (e.g., staking provider) and optionally a sub-entity. Entity and sub-entity names are matched exactly and are case-sensitive.
      - `entity` string, required — The name of the entity to filter validators by (e.g., "Lido", "Coinbase"). Matching is case-sensitive; use the exact name as returned by the entities overview endpoint.
      - `sub_entity` string — Optional sub-entity name to further filter validators within the entity. Matching is case-sensitive; use the exact name as returned by the sub-entities overview endpoint.
  - `range` union, required — Specify a date range to receive aggregated data for that period — ideal for use cases like daily income tracking for income reporting. Support for querying arbitrary time ranges using Unix timestamps, epochs, or slots will be **coming soon**, exclusively for Scale and Enterprise plans (https://beaconcha.in/pricing).
    - NamedEvaluationWindow
      - `evaluation_window` '24h' | '7d' | '30d' | '90d' | 'all_time', required — The evaluation window for aggregating metrics. All windows except `all_time` are **rolling periods**—continuously moving time windows that always end at the current epoch. Rolling windows update every epoch (~6.4 minutes), so the data always reflects the most recent period. For example, `30d` returns rewards from exactly 30 days ago until now, not a fixed calendar month. - `24h`: Last 24 hours (rolling) - `7d`: Last 7 days (rolling) - `30d`: Last 30 days (rolling) - `90d`: Last 90 days (rolling) - `all_time`: Since validator activation (not rolling)
    - TimeRangeSelectorTime — Range provided via Unix timestamp (inclusive)
      - `timestamp` TimeRangeStartEnd, required — Unix timestamp range (inclusive)
        - `start` integer, required
        - `end` integer, required
    - TimeRangeSelectorEpoch — Range provided via epoch number
      - `epoch` EpochRangeStartEnd, required — Epoch range (inclusive)
        - `start` union, required — Specify an epoch using one of the following methods. - epoch number - View: "latest", "finalized"
          - EpochByNumber
            - `number` integer, required
          - EpochByChainView
            - `view` 'latest' | 'finalized', required — - "latest": Refers to the most recent block, which may be subject to reorganization. - "finalized": Refers to the latest block that has been finalized and is not subject to change.
        - `end` union, required — Specify an epoch using one of the following methods. - epoch number - View: "latest", "finalized"
          - EpochByNumber
            - `number` integer, required
          - EpochByChainView
            - `view` 'latest' | 'finalized', required — - "latest": Refers to the most recent block, which may be subject to reorganization. - "finalized": Refers to the latest block that has been finalized and is not subject to change.
    - TimeRangeSelectorSlot — Range provided via slot number
      - `slot` SlotRangeStartEnd, required — Slot range (inclusive)
        - `start` union — Specify a slot using one of the following methods. - Slot number - Consensus layer block root - View: "latest", "finalized"
          - SlotByNumber
            - `number` integer, required — Slot by number.
          - SlotByConsensusLayerBlockRoot
            - `root` string, required — A 32-byte block root represented as a hex string with 0x prefix.
          - SlotByChainView
            - `view` 'latest' | 'finalized', required — - "latest": Refers to the most recent block, which may be subject to reorganization. - "finalized": Refers to the latest block that has been finalized and is not subject to change.
        - `end` union — Specify a slot using one of the following methods. - Slot number - Consensus layer block root - View: "latest", "finalized"
          - SlotByNumber
            - `number` integer, required — Slot by number.
          - SlotByConsensusLayerBlockRoot
            - `root` string, required — A 32-byte block root represented as a hex string with 0x prefix.
          - SlotByChainView
            - `view` 'latest' | 'finalized', required — - "latest": Refers to the most recent block, which may be subject to reorganization. - "finalized": Refers to the latest block that has been finalized and is not subject to change.

## Response `200`

Successful response.

- ValidatorPerformanceSummaryContainer — Response containing the aggregated beaconscore of the validators.
  - `data` ValidatorPerformanceSummaryData, required
    - `beaconscore` PerformanceBeaconscore, required — BeaconScore efficiency metrics for the selected scope and evaluation window. Values are ratios from 0 to 1, where 1 represents perfect duty performance.
      - `total` number, float
      - `attestation` number, float
      - `proposal` number, float
      - `sync_committee` number, float
    - `duties` PerformanceDutiesDuties, required
      - `attestation` PerformanceDutiesAttestation, required
        - `included` integer, required — Number of times the validator's attestation was included on-chain. This count includes all attestations submitted by the validator, even if they were included too late to earn a reward (such late attestations are still considered "missed" for reward purposes). "Included" reflects every attestation that made it on-chain, regardless of timeliness or eligibility for rewards. This metric indicates whether your validator is actively submitting attestations to the network.
        - `assigned` integer, required — Number of times the validator was assigned an attestation duty. This represents the total opportunities to attest, regardless of whether the validator fulfilled the duty.
        - `correct_head` integer, required — Number of times the validator attested with the correct head block. Correct references are necessary to be rewarded by the chain but incorrect references result in no reward or a penalty.
        - `correct_source` integer, required — Number of times the validator attested with the correct source block. Correct references are necessary to be rewarded by the chain but incorrect references result in no reward or a penalty.
        - `correct_target` integer, required — Number of times the validator attested with the correct target block. Correct references are necessary to be rewarded by the chain but incorrect references result in no reward or a penalty.
        - `valuable_correct_head` integer, required — Counts the number of correct head attestations that were included early enough to receive a reward. Attestations that were included too late to earn a reward (and are treated as missed for reward purposes) are not counted as valuable.
        - `valuable_correct_source` integer, required — Counts the number of correct source attestations that were included early enough to receive a reward. Attestations that were included too late to earn a reward (and are treated as missed for reward purposes) are not counted as valuable.
        - `valuable_correct_target` integer, required — Counts the number of correct target attestations that were included early enough to receive a reward. Attestations that were included too late to earn a reward (and are treated as missed for reward purposes) are not counted as valuable.
        - `avg_inclusion_delay` number, float, required — Average inclusion delay measures how quickly a validator's attestations are included in the chain, expressed in slots. Lower values indicate more timely inclusion and better performance. An ideal value of 0 means every attestation was included at the earliest possible opportunity—one slot after it was assigned to you. Note: Do not confuse this metric with the `reward.inclusion_delay` field found in the rewards endpoint, which refers to a specific reward (measured in gwei) that was only applicable prior to the Altair hardfork.
        - `avg_inclusion_delay_excluding_missed_slots` number, float, required — This is your average inclusion delay, excluding any missed blocks. - If `avg_inclusion_delay_excluding_missed_slots` is close to zero but avg_inclusion_delay is higher, this indicates that most of your attestations are included promptly, and any lost rewards are primarily due to missed blocks on the network (outside your control). - If both values are large, it suggests your validator is experiencing delays in submitting attestations, likely due to issues with your validator's setup or connectivity. Note: avg_inclusion_delay is used for reward calculations. Therefore, an `avg_inclusion_delay_excluding_missed_slots` of zero does not mean there were no missed rewards. The `avg_inclusion_delay_excluding_missed_slots` is always less than or equal to your actual `avg_inclusion_delay`.
        - `missed` integer, required — Number of times the validator missed voting on an attestation duty, including missed blocks on the network.
      - `sync_committee` ValidatorSyncCommitteeDutyParticipation, required
        - `successful` integer, required — Number of times the validator successfully participated in the sync committee.
        - `assigned` integer, required — Number of times the validator has been assigned to participate in the sync committee, excluding missed slots.
        - `missed` integer, required — Number of times the validator missed participation in the sync committee, excluding missed network slots. The `missed` is always less than or equal to your actual `missed_including_missed_slots`.
        - `missed_including_missed_slots` integer, required — Number of times the validator missed participation in the sync committee, including missed network slots. Missed network slots are beyond your control. If this value is significantly higher than `missed`, it indicates that your validator is generally performing well, and most missed rewards are due to network issues rather than validator faults. However, if both `missed` and `missed_including_missed_slots` are high, it suggests potential issues with your validator's setup or connectivity, leading to missed sync committee messages.
        - `scheduled` integer, required — Number of scheduled sync committee votes for active and upcoming sync committees.
      - `proposal` PerformanceDutiesProposal, required
        - `successful` integer, required — Number of times the validator successfully proposed a block.
        - `assigned` integer, required — Number of times the validator was assigned to propose a block.
        - `missed` integer, required — Number of times the validator either missed a scheduled block proposal or had their proposed block orphaned
        - `included_slashings` integer, required — Number of slashing proofs included in blocks proposed by the validator. A slashing proof provides cryptographic evidence that one or more validators proposing two different blocks for the same slot.
    - `finality` 'not_finalized' | 'finalized', required — Indicates the finality status of the data provided. - Finalized data cannot be changed without slashing at least one-third of all validators, providing strong economic guarantees. - Data marked as not_finalized does not have this guarantee and may still change.
  - `range` ResultRange, required — The range of data covered by the results, specified in slots, epochs, and Unix timestamps.
    - `slot` SlotRange, required
      - `start` integer, required — Slot by number.
      - `end` integer, required — Slot by number.
    - `epoch` EpochRange, required
      - `start` integer, required
      - `end` integer, required
    - `timestamp` TimeRange, required
      - `start` integer, required
      - `end` integer, required

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `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)