> ## 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 balance history > Retrieve per-epoch balance history for one or more validators. Provide a comma-separated list of validator indices or 0x-prefixed BLS pubkeys in the path parameter (up to the server-enforced limit; default 100). Use the optional query parameters to control the time window: - latest_epoch: the most recent epoch to include (defaults to the latest processed epoch) - offset: number of epochs to step back from latest_epoch before starting the window - limit: number of epochs to return (1..100, defaults to 100) The response contains one item per validator per epoch within the window, including the balance and effective balance in gwei, and week grouping metadata for downstream charting. ## OpenAPI ````yaml /api/v1/bundled.yaml get /api/v1/validator/{indexOrPubkey}/balancehistory 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}/balancehistory: get: tags: - Validators summary: Validator balance history description: >- Retrieve per-epoch balance history for one or more validators. Provide a comma-separated list of validator indices or 0x-prefixed BLS pubkeys in the path parameter (up to the server-enforced limit; default 100). Use the optional query parameters to control the time window: - latest_epoch: the most recent epoch to include (defaults to the latest processed epoch) - offset: number of epochs to step back from latest_epoch before starting the window - limit: number of epochs to return (1..100, defaults to 100) The response contains one item per validator per epoch within the window, including the balance and effective balance in gwei, and week grouping metadata for downstream charting. operationId: listValidatorBalanceHistory 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 processed epoch. Must be less than or equal to the latest processed epoch. required: false style: form explode: true schema: type: integer minimum: 0 example: 54656 - 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: >- Balance history retrieved successfully. The `data` array contains one entry per validator per epoch within the requested window. content: application/json: schema: allOf: - $ref: '#/components/schemas/types.ApiResponse' - type: object properties: data: type: array items: $ref: >- #/components/schemas/types.ApiValidatorBalanceHistoryResponse '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 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.ApiValidatorBalanceHistoryResponse: type: object description: >- Per-epoch balance snapshot for a validator, including effective balance and week grouping metadata. properties: balance: type: integer description: Validator balance in gwei at the end of the epoch. minimum: 0 example: 32014494648 effectivebalance: type: integer description: >- Effective balance in gwei used for rewards/penalties (capped at 32,000,000,000 gwei when fully effective). minimum: 0 example: 32000000000 epoch: type: integer description: Epoch number corresponding to this balance snapshot (>= 0). minimum: 0 example: 399359 validatorindex: type: integer description: Validator index to whom this balance snapshot applies (>= 0). minimum: 0 example: 34523 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 securitySchemes: ApiKeyAuthQuery: type: apiKey in: query name: apikey description: '' ApiKeyAuthHeader: type: apiKey in: header name: apikey description: '' ````