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



## OpenAPI

````yaml v3/openapi3.yaml POST /api/v2/ethereum/validators/rewards-list
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-list:
    post:
      tags:
        - Rewards
      summary: Rewards
      description: >
        Returns a breakdown of rewards for each validator for a given epoch.


        **Use case guide:** [Validator rewards](/use-cases/rewards-introduction)
        explains when to use per-epoch rewards and links to custom-range, tax,
        and missed-reward workflows.


        Use [Rewards
        Aggregated](/api-reference/ethereum/validators/rewards-aggregate) for a
        cumulative view of all validator rewards combined.


        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.
      operationId: GetValidatorRewardsList
      requestBody:
        $ref: >-
          #/components/requestBodies/validatorChainCursorPageSizeEpochNoEpochEnums
      responses:
        '200':
          $ref: '#/components/responses/ValidatorRewardsList'
        '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:
    validatorChainCursorPageSizeEpochNoEpochEnums:
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ValidatorChainCursorPageSizeBase'
              - $ref: '#/components/schemas/epochNoEnumsNamedParam'
            required:
              - epoch
              - validator
  responses:
    ValidatorRewardsList:
      description: Successful response.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ValidatorRewardsList.ContainerList'
              - $ref: '#/components/schemas/PagingRangeTemplate'
            description: >-
              Response containing detailed rewards information of the
              validators.
    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:
    ValidatorChainCursorPageSizeBase:
      type: object
      properties:
        chain:
          $ref: '#/components/schemas/Chain'
        cursor:
          $ref: '#/components/schemas/Cursor'
        page_size:
          $ref: '#/components/schemas/PageSize'
        validator:
          $ref: '#/components/schemas/validatorsSelector'
    epochNoEnumsNamedParam:
      type: object
      properties:
        epoch:
          $ref: '#/components/schemas/Epoch'
    ValidatorRewardsList.ContainerList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ValidatorRewardsList.Data'
      required:
        - data
    PagingRangeTemplate:
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/Paging'
        range:
          $ref: '#/components/schemas/ResultRange'
      required:
        - range
    Error:
      type: object
      properties:
        error:
          type: string
    Chain:
      type: string
      enum:
        - mainnet
        - hoodi
      default: mainnet
      description: The Ethereum chain to query.
    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
    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'
    Epoch:
      type: integer
      minimum: 0
    ValidatorRewardsList.Data:
      allOf:
        - $ref: '#/components/schemas/ValidatorRewardList.Validator'
        - $ref: '#/components/schemas/RewardsData'
        - $ref: '#/components/schemas/ValidatorRewardList.Finality'
    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
    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
    ValidatorRewardList.Validator:
      type: object
      properties:
        validator:
          $ref: '#/components/schemas/validator'
      required:
        - validator
    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
    ValidatorRewardList.Finality:
      type: object
      properties:
        finality:
          $ref: '#/components/schemas/FinalityParams'
      required:
        - finality
    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.
    validator:
      type: object
      properties:
        index:
          allOf:
            - $ref: '#/components/schemas/validatorIndex'
          nullable: true
        public_key:
          $ref: '#/components/schemas/validatorPublicKey'
    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.
    timestamp:
      type: integer
      minimum: 0
    validatorIndexPublicKey:
      oneOf:
        - $ref: '#/components/schemas/validatorIndex'
        - $ref: '#/components/schemas/validatorPublicKey'
    validatorIndex:
      description: Validator Index
      type: integer
      minimum: 0
    validatorPublicKey:
      type: string
      description: Public key of a validator
      pattern: ^0x[a-fA-F0-9]{96}$
    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
  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.

````