> ## 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. # Validator income detail history > Retrieve a per-epoch income breakdown for one or more validators over a bounded epoch window. Provide validator identifiers as a comma-separated list in the path parameter (indices or 0x-prefixed BLS pubkeys, up to the server-enforced limit; default 100). The window ends at `latest_epoch` (defaults to the latest finalized epoch) and spans `limit` epochs backwards. You can shift the window back in time by setting `offset`, which reduces `latest_epoch` by the given number of epochs. The response includes consensus-layer rewards/penalties in gwei and execution tips in wei (`tx_fee_reward_wei`). ## OpenAPI ````yaml /api/v1/bundled.yaml get /api/v1/validator/{indexOrPubkey}/incomedetailhistory openapi: 3.0.4 info: title: beaconcha.in API Documentation license: name: GPL-3.0 url: https://www.gnu.org/licenses/gpl-3.0.en.html description: >- > ⚠️ No new features or endpoints will be added to V1. We recommend the [V2 API](/api/overview) for all new projects. See the [migration guide](/api/v1-to-v2-migration). ## Introduction **Advanced and reliable API for accessing comprehensive Ethereum blockchain data.** - **Free Usage Policy:** The API is free to use under a fair use policy, with rate limits of 10 requests per minute per IP. - **Caching:** All responses are cached for 1 minute. - **Higher Usage Plans:** For higher usage plans, visit: [https://beaconcha.in/pricing](https://beaconcha.in/pricing). An API key is required to use these plans. ### API Key Usage API keys can be obtained at [/user/settings](https://beaconcha.in/user/settings) and must be included in requests either as a query string parameter or in the request header. #### Example: Query String Parameter ```bash curl https://beaconcha.in/api/v1/slot/1?apikey= ``` #### Example: Request Header ```bash curl -H 'apikey: ' https://beaconcha.in/api/v1/slot/1 ``` contact: {} version: '1.1' servers: - url: https://beaconcha.in description: Ethereum mainnet - url: https://hoodi.beaconcha.in description: Hoodi Ethereum testnet security: - ApiKeyAuthQuery: [] - ApiKeyAuthHeader: [] tags: - name: Epoch description: Data related to consensus layer epochs - name: Slots description: Data related to consensus layer slots - name: Validators description: Data related to consensus layer validators - name: Rewards description: Data related to validator rewards - name: Sync Committees description: Data related to sync committees - name: Rocketpool description: Data related to the rocketpool protocol - name: ETH.Store® description: Data related to the ETH.Store® metric - name: Validator deposits description: Data related to execution layer validator deposits - name: Blocks description: Data related to execution layer blocks - name: Gas description: Data related to gas prices - name: Address description: Data related to ethereum addresses - name: Network description: Network data - name: Misc description: Miscellaneous data - name: User description: User data - name: Machine Metrics description: Submit machine, beacon-node, and validator-client monitoring metrics paths: /api/v1/validator/{indexOrPubkey}/incomedetailhistory: get: tags: - Validators summary: Validator income detail history description: >- Retrieve a per-epoch income breakdown for one or more validators over a bounded epoch window. Provide validator identifiers as a comma-separated list in the path parameter (indices or 0x-prefixed BLS pubkeys, up to the server-enforced limit; default 100). The window ends at `latest_epoch` (defaults to the latest finalized epoch) and spans `limit` epochs backwards. You can shift the window back in time by setting `offset`, which reduces `latest_epoch` by the given number of epochs. The response includes consensus-layer rewards/penalties in gwei and execution tips in wei (`tx_fee_reward_wei`). operationId: listValidatorIncomeDetailHistory parameters: - name: indexOrPubkey in: path description: >- Comma-separated validator indices and/or public keys (maximum 100 items by default). required: true style: simple explode: false schema: $ref: '#/components/schemas/primitives.indicesOrPubkeys' - name: latest_epoch in: query description: >- Most recent epoch to include (inclusive). Defaults to the latest finalized epoch. Must be less than or equal to the latest finalized epoch at request time. required: false style: form explode: true schema: type: integer minimum: 0 example: 399359 - name: offset in: query description: >- Number of epochs to skip backwards from `latest_epoch` before starting the window. Must be non-negative and not exceed `latest_epoch`. required: false style: form explode: true schema: type: integer minimum: 0 example: 0 default: 0 - name: limit in: query description: >- Number of epochs to return in the window. Allowed range is 1 to 100. Defaults to 100. required: false style: form explode: true schema: type: integer minimum: 1 maximum: 100 default: 100 example: 50 responses: '200': description: >- Income details were retrieved successfully. The `data` array contains one entry per validator per epoch within the requested window. Items are sorted by epoch (descending) and then by validator index (ascending). content: application/json: schema: allOf: - $ref: '#/components/schemas/types.ApiResponse' - type: object properties: data: type: array items: $ref: >- #/components/schemas/types.ApiValidatorIncomeHistoryResponse '400': description: >- The request is invalid (for example, malformed identifiers or invalid query parameters). content: application/json: schema: $ref: '#/components/schemas/types.ApiErrorResponse' examples: invalidParam: summary: Invalid validator identifier value: status: 'ERROR: invalid validator-parameter' data: null tooMany: summary: Too many identifiers value: status: 'ERROR: only a maximum of 100 query parameters are allowed' data: null unresolvedPubkeys: summary: Pubkey did not resolve to an index value: status: >- ERROR: invalid validator argument, pubkey(s) did not resolve to a validator index data: null noValidators: summary: No validators provided value: status: 'ERROR: no validators provided' data: null invalidLatestEpoch: summary: Invalid latest_epoch parameter value: status: 'ERROR: invalid latest epoch parameter' data: null invalidOffset: summary: Invalid offset parameter value: status: 'ERROR: invalid offset parameter' data: null invalidLimit: summary: Invalid limit parameter value: status: 'ERROR: invalid limit parameter' data: null dbError: summary: Database retrieval error value: status: 'ERROR: could not retrieve db results' data: null '500': description: An unexpected server error occurred while processing your request. content: application/json: schema: $ref: '#/components/schemas/types.ApiErrorResponse' examples: serverError: summary: Internal error value: status: 'ERROR: internal server error' data: null components: schemas: primitives.indicesOrPubkeys: type: string description: > Comma-separated list (no spaces) of validator identifiers. Each identifier must be either: - A validator index as a base-10 integer (for example, 652648) - A BLS public key as a 96-hex-character string with or without the 0x prefix (case-insensitive) Resolution and limits: - The server resolves public keys to validator indices before querying data. - The total number of identifiers must not exceed the server-enforced limit (default 100). - Identifiers that cannot be parsed or resolved result in HTTP 400. example: 1,2,3 types.ApiResponse: type: object description: Standard success envelope used by all API endpoints. properties: status: type: string description: >- HTTP-independent status of the API operation. For successful responses this is always "OK". enum: - OK data: description: Response payload specific to the endpoint. nullable: true x-omitempty: true types.ApiValidatorIncomeHistoryResponse: type: object description: >- Per-epoch income detail entry for a validator, including consensus-layer reward/penalty breakdown and execution tips, with week grouping metadata. properties: epoch: type: integer description: Epoch number this income record belongs to (>= 0). minimum: 0 example: 398940 income: $ref: '#/components/schemas/types.ApiValidatorIncomeHistory' validatorindex: type: integer description: Validator index (>= 0). minimum: 0 example: 1815428 week: type: integer description: Epoch-based week number computed as `epoch / (EpochsPerDay * 7)`. minimum: 0 example: 253 week_start: type: string format: date-time description: Start timestamp (UTC, RFC 3339) of the week containing `epoch`. example: '2025-10-07T12:00:23Z' week_end: type: string format: date-time description: End timestamp (UTC, RFC 3339) of the week containing `epoch`. example: '2025-10-14T12:00:23Z' types.ApiErrorResponse: type: object description: Standard error envelope returned when a request fails. properties: status: type: string description: >- Human-readable error indicator and message. The value begins with "ERROR:" followed by details. example: 'ERROR: ' data: type: string description: Optional additional context for the error. Null in most cases. nullable: true default: null types.ApiValidatorIncomeHistory: type: object description: >- Detailed per-epoch income breakdown for a validator. Unless noted otherwise, all amounts are in gwei. properties: attestation_head_reward: type: integer description: Reward from correct head vote in the attestation, in gwei. example: 1024 attestation_source_penalty: type: integer description: >- Penalty from incorrect/missed source vote, in gwei (non-positive; represented as unsigned magnitude when stored by some backends). example: 0 attestation_source_reward: type: integer description: Reward from correct source vote in the attestation, in gwei. example: 2048 attestation_target_penalty: type: integer description: >- Penalty from incorrect/missed target vote, in gwei (non-positive; represented as unsigned magnitude when stored by some backends). example: 0 attestation_target_reward: type: integer description: Reward from correct target vote in the attestation, in gwei. example: 3072 finality_delay_penalty: type: integer description: >- Penalty due to finality delays in the network (applies during periods with no finality), in gwei. example: 0 proposals_missed: type: integer description: >- Number of scheduled block proposals the validator missed during this epoch. minimum: 0 example: 0 proposer_attestation_inclusion_reward: type: integer description: Proposer reward for including attestations, in gwei. example: 512 proposer_slashing_inclusion_reward: type: integer description: Proposer reward for including a proposer slashing, in gwei. example: 0 proposer_sync_inclusion_reward: type: integer description: >- Proposer reward for including a sync committee signature set, in gwei. example: 0 slashing_penalty: type: integer description: Penalty due to being slashed or due to correlations, in gwei. example: 0 slashing_reward: type: integer description: >- Reward earned from participating in a slashing (as whistleblower/aggregator), in gwei. example: 0 sync_committee_penalty: type: integer description: Penalty from missed/incorrect sync committee participation, in gwei. example: 0 sync_committee_reward: type: integer description: >- Reward from participating in the sync committee for the epoch, in gwei. example: 0 tx_fee_reward_wei: type: string description: >- Execution-layer fee reward (priority fees and/or MEV payment) attributed to the validator for this epoch, as a decimal string in wei. example: '470167509840' securitySchemes: ApiKeyAuthQuery: type: apiKey in: query name: apikey description: '' ApiKeyAuthHeader: type: apiKey in: header name: apikey description: '' ````