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

# Rewards Aggregated

> Returns the cumulative rewards for a set 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 rewards](/use-cases/rewards-introduction) explains when to use aggregate rewards and how to turn the response into reports and comparisons.

Use [Rewards](/api-reference/ethereum/validators/rewards-list) for a rewards breakdown of each validator.

Note: Only finalized epochs are supported for rewards data.

**Attribution Required:** If you display BeaconScore data publicly, you must include appropriate attribution. See our [BeaconScore License](/legal/beaconscore-license) and [License Materials](/legal/license-materials) for badges and usage guidelines.

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




## OpenAPI

````yaml /v3/bundled.yaml post /api/v2/ethereum/validators/rewards-aggregate
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/ethereum/validators/rewards-aggregate:
    post:
      tags:
        - Rewards
      summary: Rewards Aggregated
      description: >
        Returns the cumulative rewards for a set 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 rewards](/use-cases/rewards-introduction)
        explains when to use aggregate rewards and how to turn the response into
        reports and comparisons.


        Use [Rewards](/api-reference/ethereum/validators/rewards-list) for a
        rewards breakdown of each validator.


        Note: Only finalized epochs are supported for rewards data.


        **Attribution Required:** If you display BeaconScore data publicly, you
        must include appropriate attribution. See our [BeaconScore
        License](/legal/beaconscore-license) and [License
        Materials](/legal/license-materials) for badges and usage guidelines.


        **Coming Soon:** Support for querying arbitrary time ranges using Unix
        timestamps, epochs, or slots — exclusively for [Scale and Enterprise
        plans](https://beaconcha.in/pricing).
      operationId: GetValidatorRewardsAggregate
      requestBody:
        $ref: '#/components/requestBodies/aggregateValidatorChainStartEnd'
      responses:
        '200':
          $ref: '#/components/responses/ValidatorRewardsAggregate'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          $ref: '#/components/responses/DefaultError'
components:
  requestBodies:
    aggregateValidatorChainStartEnd:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AggregateValidatorChainStartEnd'
  responses:
    ValidatorRewardsAggregate:
      description: Successful response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidatorRewardsAggregate.ContainerList'
    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.
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: The requested resource was not found.
    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:
    AggregateValidatorChainStartEnd:
      type: object
      properties:
        chain:
          $ref: '#/components/schemas/Chain'
        validator:
          $ref: '#/components/schemas/validatorsSelector'
        range:
          $ref: '#/components/schemas/timeRangeSelector'
      required:
        - validator
        - range
    ValidatorRewardsAggregate.ContainerList:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ValidatorRewardsAggregate.Data'
        range:
          $ref: '#/components/schemas/ResultRange'
      description: Response containing aggregated rewards information of the validators.
      required:
        - data
        - range
    Error:
      type: object
      properties:
        error:
          type: string
    Chain:
      type: string
      enum:
        - mainnet
        - hoodi
      default: mainnet
      description: The Ethereum chain to query.
    validatorsSelector:
      description: >-
        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.
          
      oneOf:
        - $ref: '#/components/schemas/ValidatorsByIdentifiers'
        - $ref: '#/components/schemas/ValidatorsByDashboard'
        - $ref: '#/components/schemas/ValidatorsByDeposit'
        - $ref: '#/components/schemas/ValidatorsByWithdrawal'
        - $ref: '#/components/schemas/ValidatorsByEntity'
    timeRangeSelector:
      description: >
        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).
      oneOf:
        - $ref: '#/components/schemas/NamedEvaluationWindow'
        - $ref: '#/components/schemas/timeRangeSelectorTime'
          title: 💎 Unix Timestamp
        - $ref: '#/components/schemas/timeRangeSelectorEpoch'
          title: 💎 Epoch
        - $ref: '#/components/schemas/timeRangeSelectorSlot'
          title: 💎 Slot
    ValidatorRewardsAggregate.Data:
      allOf:
        - $ref: '#/components/schemas/RewardsData'
        - $ref: '#/components/schemas/NamedFinalityParams'
    ResultRange:
      type: object
      description: >
        The time span actually covered by the returned results — from the first
        to the last matching data point — specified in slots, epochs, and Unix
        timestamps.


        This reflects the data that was found, not the range that was queried.
        When no data is found, it falls back to the requested range, or to the
        full available history if no range was given.
      properties:
        slot:
          $ref: '#/components/schemas/SlotRange'
        epoch:
          $ref: '#/components/schemas/EpochRange'
        timestamp:
          $ref: '#/components/schemas/TimeRange'
      required:
        - slot
        - epoch
        - timestamp
    ValidatorsByIdentifiers:
      type: object
      title: Indices/Pubkeys
      properties:
        validator_identifiers:
          $ref: '#/components/schemas/validatorIndexPublicKeys'
      required:
        - validator_identifiers
    ValidatorsByDashboard:
      type: object
      title: Dashboard
      properties:
        dashboard_id:
          $ref: '#/components/schemas/dashboardID'
        group_id:
          $ref: '#/components/schemas/dashboardGroupID'
      required:
        - dashboard_id
    ValidatorsByDeposit:
      type: object
      title: 💎 Deposit
      properties:
        deposit_address:
          $ref: '#/components/schemas/ExecutionLayerAddress'
      required:
        - deposit_address
    ValidatorsByWithdrawal:
      type: object
      title: 💎 Withdrawal
      properties:
        withdrawal:
          $ref: '#/components/schemas/AddressOrCredential'
      required:
        - withdrawal
    ValidatorsByEntity:
      type: object
      title: 💎 Entity
      description: >
        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.
      properties:
        entity:
          type: string
          description: >
            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:
          type: string
          description: >
            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.
      required:
        - entity
    NamedEvaluationWindow:
      type: object
      title: Fixed Window
      properties:
        evaluation_window:
          $ref: '#/components/schemas/EvaluationWindow'
      required:
        - evaluation_window
    timeRangeSelectorTime:
      type: object
      title: Unix Timestamp
      description: Range provided via Unix timestamp (inclusive)
      properties:
        timestamp:
          $ref: '#/components/schemas/timeRangeStartEnd'
      required:
        - timestamp
    timeRangeSelectorEpoch:
      type: object
      title: Epoch
      description: Range provided via epoch number
      properties:
        epoch:
          $ref: '#/components/schemas/epochRangeStartEnd'
      required:
        - epoch
    timeRangeSelectorSlot:
      type: object
      title: Slot
      description: Range provided via slot number
      properties:
        slot:
          $ref: '#/components/schemas/slotRangeStartEnd'
      required:
        - slot
    RewardsData:
      type: object
      properties:
        total:
          $ref: '#/components/schemas/wei'
          description: >-
            Total net rewards (rewards minus penalties) earned by the validator
            in the specified range.
        total_reward:
          $ref: '#/components/schemas/wei'
          description: Total rewards earned by the validator in the specified range.
        total_penalty:
          $ref: '#/components/schemas/wei'
          description: Total penalties incurred by the validator in the specified range.
        total_missed:
          $ref: '#/components/schemas/wei'
          description: >
            Total missed rewards by the validator in the specified range.

            Missed rewards could have been earned if the validator had performed
            perfectly.
        attestation:
          $ref: '#/components/schemas/attestationRewards'
        sync_committee:
          $ref: '#/components/schemas/rewardBreakdown'
        proposal:
          $ref: '#/components/schemas/proposalRewards'
      required:
        - total
        - total_reward
        - total_penalty
        - attestation
        - sync_committee
        - proposal
    NamedFinalityParams:
      type: object
      properties:
        finality:
          $ref: '#/components/schemas/FinalityParams'
    SlotRange:
      type: object
      properties:
        start:
          $ref: '#/components/schemas/Slot'
        end:
          $ref: '#/components/schemas/Slot'
      required:
        - start
        - end
    EpochRange:
      type: object
      properties:
        start:
          $ref: '#/components/schemas/Epoch'
        end:
          $ref: '#/components/schemas/Epoch'
      required:
        - start
        - end
    TimeRange:
      type: object
      properties:
        start:
          $ref: '#/components/schemas/timestamp'
        end:
          $ref: '#/components/schemas/timestamp'
      required:
        - start
        - end
    validatorIndexPublicKeys:
      description: >
        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.
      type: array
      items:
        $ref: '#/components/schemas/validatorIndexPublicKey'
      minItems: 1
      maxItems: 100
    dashboardID:
      description: >
        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).
      type: integer
      x-go-type: '*int'
      minimum: 0
    dashboardGroupID:
      description: >-
        Optional beaconcha.in dashboard group ID. If no group ID is provided,
        all validators in the dashboard are considered.
      type: integer
      minimum: 0
      nullable: true
    ExecutionLayerAddress:
      type: string
      pattern: ^0x[a-fA-F0-9]{40}$
      description: A standard Ethereum address (20-byte hex string with 0x prefix).
    AddressOrCredential:
      type: string
      pattern: ^(0x)?[0-9a-fA-F]{40}$|^(0x)?0[012][0-9a-fA-F]{62}$
      description: >
        Either an execution layer address (20-byte hex string with 0x prefix) or
        a full 32-byte withdrawal credential.
    EvaluationWindow:
      type: string
      enum:
        - 24h
        - 7d
        - 30d
        - 90d
        - all_time
      description: >
        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)
    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
    epochRangeStartEnd:
      type: object
      description: Epoch range (inclusive)
      properties:
        start:
          $ref: '#/components/schemas/EpochSelector'
          description: Start Epoch
        end:
          $ref: '#/components/schemas/EpochSelector'
          description: End Epoch
      required:
        - start
        - end
    slotRangeStartEnd:
      type: object
      description: Slot range (inclusive)
      properties:
        start:
          $ref: '#/components/schemas/SlotSelector'
          description: Start Slot
        end:
          $ref: '#/components/schemas/SlotSelector'
          description: End Slot
    wei:
      type: string
      description: Amount in wei (1 ETH = 10^18 wei)
      pattern: ^(0|-?[1-9][0-9]*)$
    attestationRewards:
      type: object
      properties:
        total:
          $ref: '#/components/schemas/wei'
          description: Total rewards earned from attestations.
        head:
          $ref: '#/components/schemas/rewardBreakdownHead'
        source:
          $ref: '#/components/schemas/rewardBreakdown'
          description: >
            Reward or penalty for correct or incorrect source votes in
            attestations.
        target:
          $ref: '#/components/schemas/rewardBreakdown'
          description: >
            Reward or penalty for correct or incorrect target votes in
            attestations.
        inactivity_leak_penalty:
          $ref: '#/components/schemas/wei'
          description: >
            If the chain fails to finalize, it enters "inactivity leak" mode.

            In this state, inactive validators receive escalating penalties that
            increase over time.


            This mechanism encourages validators to resume participation and
            helps restore finality by gradually removing non-participating
            validators from the active set.
        inclusion_delay:
          $ref: '#/components/schemas/attestationInclusionDelay'
          nullable: true
      required:
        - head
        - source
        - target
        - inactivity_leak_penalty
    rewardBreakdown:
      allOf:
        - $ref: '#/components/schemas/rewardBreakdownBase'
    proposalRewards:
      type: object
      properties:
        total:
          $ref: '#/components/schemas/wei'
          description: |
            Total rewards earned from block proposals.
        execution_layer_reward:
          $ref: '#/components/schemas/wei'
          description: >
            Rewards earned from execution layer activities, which can be either
            transaction fees or MEV rewards, depending on the block.
        attestation_inclusion_reward:
          $ref: '#/components/schemas/wei'
          description: >
            Rewards for including attestations in the proposed block.

            Proposers receive a reward based on the attestation rewards included
            in their block.
        sync_inclusion_reward:
          $ref: '#/components/schemas/wei'
          description: >
            Rewards for including sync committee contributions in the proposed
            block.

            Proposers receive a reward based on the sync committee rewards
            included in their block.
        slashing_inclusion_reward:
          $ref: '#/components/schemas/wei'
          description: >
            Rewards for including slashing proofs in the block.

            Proposers earn a portion of the slashed validators' effective
            balance.
        missed_cl_reward:
          $ref: '#/components/schemas/wei'
          description: >
            Estimated consensus layer rewards lost due to missed or orphaned
            block proposals.


            The actual missed value is impossible to be determined, we estimate
            it using the median reward from the 32 surrounding blocks - 16
            before and 16 after, [n-16, n+16).
        missed_el_reward:
          $ref: '#/components/schemas/wei'
          description: >
            Estimated execution layer rewards lost due to missed or orphaned
            block proposals.


            The actual missed value is impossible to be determined, we estimate
            it using the median reward from the 32 surrounding blocks - 16
            before and 16 after, [n-16, n+16).
      required:
        - total
        - execution_layer_reward
        - attestation_inclusion_reward
        - sync_inclusion_reward
        - slashing_inclusion_reward
        - missed_cl_reward
        - missed_el_reward
    FinalityParams:
      type: string
      description: |
        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.
      enum:
        - not_finalized
        - finalized
    Slot:
      type: integer
      minimum: 0
      description: Slot by number.
    Epoch:
      type: integer
      minimum: 0
    timestamp:
      type: integer
      minimum: 0
    validatorIndexPublicKey:
      oneOf:
        - $ref: '#/components/schemas/validatorIndex'
        - $ref: '#/components/schemas/validatorPublicKey'
    EpochSelector:
      description: |
        Specify an epoch using one of the following methods.
        - epoch number
        - View: "latest", "finalized" 
      oneOf:
        - $ref: '#/components/schemas/EpochByNumber'
        - $ref: '#/components/schemas/EpochByChainView'
    SlotSelector:
      description: |
        Specify a slot using one of the following methods.
        - Slot number
        - Consensus layer block root
        - View: "latest", "finalized" 
      oneOf:
        - $ref: '#/components/schemas/SlotByNumber'
        - $ref: '#/components/schemas/SlotByConsensusLayerBlockRoot'
        - $ref: '#/components/schemas/SlotByChainView'
      default: latest
    rewardBreakdownHead:
      allOf:
        - $ref: '#/components/schemas/rewardBreakdownBase'
      description: >
        A detailed breakdown of rewards and penalties related to Head Vote
        duties.


        **Important Note on Penalty:** The 'penalty' field for head votes was
        only applicable before the Altair hardfork (Epoch 74240, Oct 27, 2021).
        After Altair, there is no penalty for incorrect head votes; only missed
        rewards. 
    attestationInclusionDelay:
      nullable: true
      description: >
        **Note:** This reward was only applicable before the Altair hardfork
        (Epoch 74240, Oct 27, 2021).


        Prior to Altair, validators earned extra rewards for including
        attestations with minimal delay—the faster the inclusion, the greater
        the reward. 

        Since Altair, this incentive was removed and timely inclusion became a
        strict requirement: head votes must now be included in the immediate
        next slot. 

        As a result, this field is always null for epochs after Altair, but may
        have nonzero values for earlier epochs.


        Note: Do not confuse this metric with the
        `performance.avg_inclusion_delay` field found in the performance
        endpoint, which refers to the average delay in slots for attestations to
        be included on-chain.
      type: object
      properties:
        total:
          $ref: '#/components/schemas/wei'
          description: >
            Total rewards earned by the validator for timely inclusion of
            attestations.

            There is no penalty for delayed inclusion, only missed rewards. 
        missed_reward:
          $ref: '#/components/schemas/wei'
          description: >
            Missed rewards are the potential earnings lost due delayed
            attestations that you could have earned if performed correctly. 

            This value shows the difference between the maximum possible reward
            and the actual reward received.

            Returned as a positive value representing unearned rewards.
      required:
        - total
        - missed_reward
    rewardBreakdownBase:
      type: object
      properties:
        total:
          $ref: '#/components/schemas/wei'
          description: >
            Net result for this duty (reward minus penalty).


            Positive values indicate net rewards earned; negative values
            indicate net penalties.
        reward:
          $ref: '#/components/schemas/wei'
          description: >
            Reward is the amount earned for correctly and promptly performing
            duties. Represents the positive balance increase received.
        penalty:
          $ref: '#/components/schemas/wei'
          description: >
            Penalty is the amount deducted from your balance for missing or
            incorrectly performing duties.

            This is always a positive value, representing the loss incurred in
            addition to missed rewards.


            When missing a duty, you earn no reward and also incur a penalty,
            resulting in a net negative impact on your balance.
        missed_reward:
          $ref: '#/components/schemas/wei'
          description: >
            Missed rewards are the potential earnings lost due to missed or
            delayed duties that you could have earned if performed correctly. 

            This value shows the difference between the maximum possible reward
            and the actual reward received.


            Returned as a positive value representing unearned rewards.
      required:
        - total
        - reward
        - penalty
        - missed_reward
    validatorIndex:
      description: Validator Index
      type: integer
      minimum: 0
    validatorPublicKey:
      type: string
      description: Public key of a validator
      pattern: ^0x[a-fA-F0-9]{96}$
    EpochByNumber:
      title: Number
      type: object
      properties:
        number:
          $ref: '#/components/schemas/Epoch'
      required:
        - number
    EpochByChainView:
      title: View
      type: object
      properties:
        view:
          allOf:
            - $ref: '#/components/schemas/ChainView'
          description: >
            - "latest": Refers to the most recent epoch, which may not yet be
            finalized.

            - "finalized": Refers to the latest epoch that has been finalized
            and is not subject to change.
      required:
        - view
    SlotByNumber:
      title: Number
      type: object
      properties:
        number:
          $ref: '#/components/schemas/Slot'
      required:
        - number
    SlotByConsensusLayerBlockRoot:
      title: Root
      type: object
      properties:
        root:
          $ref: '#/components/schemas/ConsensusLayerBlockRoot'
      required:
        - root
    SlotByChainView:
      title: View
      type: object
      properties:
        view:
          allOf:
            - $ref: '#/components/schemas/ChainView'
          description: >
            - "latest": Refers to the most recent slot, which may be subject to
            reorganization.

            - "finalized": Refers to the latest slot that has been finalized and
            is not subject to change.
      required:
        - view
    ChainView:
      type: string
      enum:
        - latest
        - finalized
      description: >
        - "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.
    ConsensusLayerBlockRoot:
      type: string
      pattern: ^0x[a-fA-F0-9]{64}$
      description: A 32-byte block root represented as a hex string with 0x prefix.
  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.

````