> ## 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 > Returns basic information about a set of validators at the current epoch. Data returned by the endpoint is based on the latest completed epoch of the beacon chain (not finalized). ## OpenAPI ````yaml /v3/bundled.yaml post /api/v2/ethereum/validators 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: post: tags: - General summary: Validator description: > Returns basic information about a set of validators at the current epoch. Data returned by the endpoint is based on the latest completed epoch of the beacon chain (not finalized). operationId: GetValidatorOverview requestBody: $ref: '#/components/requestBodies/validatorChainCursorPageSize' responses: '200': $ref: '#/components/responses/ValidatorOverview' '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: validatorChainCursorPageSize: content: application/json: schema: allOf: - $ref: '#/components/schemas/ValidatorChainCursorPageSizeBase' - type: object required: - validator responses: ValidatorOverview: description: Successful response. content: application/json: schema: allOf: - $ref: '#/components/schemas/ValidatorOverview.ContainerList' - $ref: '#/components/schemas/PagingRangeTemplate' description: Response containing basic information about the validator. 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' ValidatorOverview.ContainerList: type: object properties: data: type: array items: $ref: '#/components/schemas/ValidatorOverview.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' ValidatorOverview.Data: type: object properties: validator: $ref: '#/components/schemas/validator' slashed: type: boolean status: $ref: '#/components/schemas/Validator.Status' online: type: boolean nullable: true withdrawal_credentials: $ref: '#/components/schemas/withdrawalCredential' life_cycle_epochs: $ref: '#/components/schemas/LifeCycleEpochs' balances: $ref: '#/components/schemas/validatorBalancesHead' finality: $ref: '#/components/schemas/FinalityParamsOnlyNoFinalization' required: - validator - slashed - status - withdrawal_credentials - life_cycle_epochs - balances - 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 validator: type: object properties: index: allOf: - $ref: '#/components/schemas/validatorIndex' nullable: true public_key: $ref: '#/components/schemas/validatorPublicKey' Validator.Status: type: string enum: - pending_initialized - pending_queued - active_ongoing - active_exiting - active_slashed - exited_unslashed - exited_slashed - withdrawal_possible - withdrawal_done - unknown withdrawalCredential: type: object properties: type: $ref: '#/components/schemas/withdrawalCredentialType' prefix: $ref: '#/components/schemas/withdrawalCredentialPrefix' credential: $ref: '#/components/schemas/withdrawalCredentialPrimitive' address: $ref: '#/components/schemas/ExecutionLayerAddress' nullable: true description: Present only if type is execution_address required: - type - prefix - credential LifeCycleEpochs: type: object description: >- Epochs marking significant lifecycle events for the validator. Unlike the official spec, null is returned for events that have not yet occurred, instead of using "FAR_FUTURE_EPOCH" (max uint64), to simplify client handling. properties: activation_eligibility: description: >- The epoch at which the validator became eligible for activation by meeting the activation criteria. type: integer nullable: true activation: description: >- The epoch at which the validator was activated and started participating in the consensus process & earning rewards. type: integer nullable: true exit: type: integer description: >- The epoch at which the validator exited and stopped participating in the consensus process. nullable: true withdrawable: type: integer description: >- The epoch at which the validator became eligible for withdrawal after they have exited. nullable: true validatorBalancesHead: allOf: - $ref: '#/components/schemas/ValidatorBalancesBase' - type: object description: > The balances object provides detailed information about a validator's balances at the head of the chain. Balances are measured immediately before the first slot of the head chain. For example, a balance reported for epoch 10 reflects the state after the final slot of epoch 9 and before the first slot of epoch 10. For more details about balances, see: https://eth2book.info/latest/part2/incentives/balances/ FinalityParamsOnlyNoFinalization: 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 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. validatorIndex: description: Validator Index type: integer minimum: 0 validatorPublicKey: type: string description: Public key of a validator pattern: ^0x[a-fA-F0-9]{96}$ withdrawalCredentialType: type: string description: > Specifies whether the withdrawal credential is a BLS withdrawal credential or an execution address withdrawal credential. enum: - bls - execution_address withdrawalCredentialPrefix: type: string enum: - '0x00' - '0x01' - '0x02' description: > Hexadecimal prefix indicating the type of withdrawal credential: - "0x00": BLS withdrawal credential - "0x01": Execution address withdrawal credential - "0x02": Execution address withdrawal credential with consolidation support (Electra Fork) Credentials can be upgraded in one direction only: - From "0x00" (BLS) to "0x01" (execution address) - From "0x01" to "0x02" (consolidation-enabled execution address) Downgrades are not permitted. withdrawalCredentialPrimitive: type: string pattern: ^(0x)?0[012][0-9a-fA-F]{62}$ description: >- A full 32-byte withdrawal credential represented as a hex string with 0x prefix. ValidatorBalancesBase: type: object properties: current: $ref: '#/components/schemas/wei' description: > The validator's balance at a given state. This includes all rewards and penalties accrued up to that point, excluding any withdrawn amounts. effective: $ref: '#/components/schemas/wei' description: > The effective balance is the amount used to calculate rewards and penalties for the validator on the consensus layer. It relates to the current balance to some extent, but is not the same. Unlike the current balance, the effective balance is updated less frequently, only in whole ETH increments, and is subject to a maximum cap: 32 ETH for withdrawal credential prefixes "0x00" or "0x01", and 2048 ETH for prefix "0x02". required: - current - effective 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' wei: type: string description: Amount in wei (1 ETH = 10^18 wei) pattern: ^(0|-?[1-9][0-9]*)$ 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. ````