> ## 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 Statuses > Returns the distribution of validator states across the network or a given validator filter. By default it returns the network distribution, but you might pass the optional validator filter to get a breakdown of states for a specific set of validators (e.g. your own). ## OpenAPI ````yaml /v3/bundled.yaml post /api/v2/ethereum/state/validator-statuses 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/state/validator-statuses: post: tags: - Network summary: 👀 Validator Statuses description: > Returns the distribution of validator states across the network or a given validator filter. By default it returns the network distribution, but you might pass the optional validator filter to get a breakdown of states for a specific set of validators (e.g. your own). operationId: GetValidatorStatuses requestBody: $ref: '#/components/requestBodies/optionalValidatorChain' responses: '200': $ref: '#/components/responses/NetworkValidatorStates' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimitExceeded' default: $ref: '#/components/responses/DefaultError' components: requestBodies: optionalValidatorChain: description: '`validator` is optional in this request body' content: application/json: schema: allOf: - type: object properties: chain: $ref: '#/components/schemas/Chain' validator: $ref: '#/components/schemas/nullableValidatorSelector' example: chain: mainnet responses: NetworkValidatorStates: description: Successful response. content: application/json: schema: $ref: '#/components/schemas/NetworkValidatorStates.Container' 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. NotFound: description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: The requested resource was not found. RateLimitExceeded: description: Rate Limit Exceeded content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Rate limit exceeded. 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: Chain: type: string enum: - mainnet - hoodi default: mainnet description: The Ethereum chain to query. nullableValidatorSelector: description: >- `validator` is optional in this request body. If not provided, results will be unfiltered. nullable: true default: null allOf: - $ref: '#/components/schemas/validatorsSelector' NetworkValidatorStates.Container: type: object properties: data: $ref: '#/components/schemas/NetworkValidatorStates.Data' description: Response containing the current state of the network validators. required: - data Error: type: object properties: error: type: string 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' NetworkValidatorStates.Data: type: object description: > Distribution of validators across the Ethereum validator lifecycle states. Ethereum validators progress through a defined lifecycle: 1. **Pending** — Deposit made, waiting for activation (initialized → queued). 2. **Active** — Participating in consensus duties (ongoing → exiting → slashed). 3. **Exited** — Left the active set, waiting for withdrawal eligibility. 4. **Withdrawal** — Balance eligible for or already withdrawn to the execution layer. Each state includes the count of validators and their total effective balance. properties: total: $ref: '#/components/schemas/StateValidators' description: >- Aggregate across every lifecycle state — the total validator count and their combined effective balance. pending_initialized: $ref: '#/components/schemas/StateValidators' description: > Validators whose deposit has been included on the beacon chain but have not yet been added to the activation queue. This is the first state after a deposit is processed. The validator is waiting for the deposit to be recognized and queued. pending_queued: $ref: '#/components/schemas/StateValidators' description: > Validators that have been added to the activation queue and are waiting their turn to become active. The wait time depends on the current activation churn limit and the number of validators ahead in the queue. active_ongoing: $ref: '#/components/schemas/StateValidatorsWithOnline' description: > Validators that are fully active and performing consensus duties (attesting, proposing blocks, participating in sync committees). This is the normal operating state for a healthy validator. active_exiting: $ref: '#/components/schemas/StateValidatorsWithOnline' description: > Validators that have submitted a voluntary exit request and are in the process of leaving the active set. They continue to perform duties and earn/lose rewards until their exit epoch is reached. active_slashed: $ref: '#/components/schemas/StateValidatorsWithOnline' description: > Validators that have been penalized (slashed) for protocol violations such as double voting or surround voting. Slashed validators are forcibly exited and face a penalty that increases with the number of other validators slashed in the same period. exited_unslashed: $ref: '#/components/schemas/StateValidators' description: > Validators that have voluntarily exited the active set without any slashing. They are waiting for the withdrawal eligibility delay (256 epochs ≈ 27 hours) before their balance can be withdrawn. exited_slashed: $ref: '#/components/schemas/StateValidators' description: > Validators that have exited the active set after being slashed. They are waiting for the withdrawal eligibility delay before their remaining balance (after penalties) can be withdrawn. withdrawal_possible: $ref: '#/components/schemas/StateValidators' description: > Validators whose withdrawal eligibility delay has passed and whose balance is ready to be swept by the withdrawal clock. The actual withdrawal happens when the sweep clock reaches the validator's index. withdrawal_done: $ref: '#/components/schemas/StateValidators' description: > Validators whose full balance has been withdrawn to the execution layer. These validators have completed their entire lifecycle and are no longer part of the beacon chain in any active capacity. required: - total - pending_initialized - pending_queued - active_ongoing - active_exiting - active_slashed - exited_unslashed - exited_slashed - withdrawal_possible - withdrawal_done 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 StateValidators: type: object properties: count: type: integer description: The number of validators in the state. effective_balance: $ref: '#/components/schemas/wei' required: - count - effective_balance StateValidatorsWithOnline: type: object properties: count: type: integer description: The number of validators in the state. effective_balance: $ref: '#/components/schemas/wei' online_count: type: integer description: >- The number of validators in this state that are currently online and participating in the consensus process. online_effective_balance: $ref: '#/components/schemas/wei' description: >- The effective balance of validators in this state that are currently online and participating in the consensus process. required: - count - effective_balance - online_count - online_effective_balance 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. wei: type: string description: Amount in wei (1 ETH = 10^18 wei) pattern: ^(0|-?[1-9][0-9]*)$ 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}$ 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. ````