> ## 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 Queue Consolidation Details > Returns a flat, paginated list of consolidation requests involving the selected validators, whether as source (balance being merged away) or as target (balance being received). The response is not limited to requests that are still in flight: it covers the complete history of consolidations for the selected validators, back to the Pectra fork (7 May 2025). Pass `status_filter: completed` to retrieve only consolidations that have already settled. Each entry pairs a source validator with a target validator. A single validator may appear in multiple entries across both roles. Use `role_filter` to keep only the entries where a selected validator is the source, or only those where it is the target — for example, to list every validator that was ever merged into a given target validator. Which fields an entry carries depends on its `status`: | `status` | Fields set | |---|---| | `pending` | `execution_layer` — the submitting transaction | | `queued` | `source_exit_at`, `estimated_processed_at` | | `completed` | `amount`, `processed_slot` | | `rejected` | `reject_reason` | A `pending` entry becomes `queued` once the consensus layer picks the request up out of the execution-layer contract, which releases at most two consolidation requests per block. Pending and queued entries appear first, ordered by queue position (soonest processed first). Completed and rejected entries follow, ordered by submission time (most recent first). Use `status_filter` to narrow the response to a single status, e.g. only `rejected` entries. A rejected entry whose `reject_reason` is `source_equals_target` is not a failed consolidation — it is a failed switch to compounding credentials, which the consensus layer reports through the consolidation path because both requests share one contract and one structure. A common cause is asking a validator that already has `0x02` credentials to switch again. Use [/api/v2/ethereum/validators/queues/compounding-switches](/api-reference/ethereum/validators/queues/compounding-switches) to retrieve those entries as switches. Use this endpoint in combination with the queue overview at [/api/v2/ethereum/validators/queues](/api-reference/ethereum/validators/queues) for a complete picture. **Temporary restriction:** the validator selector must resolve to no more than 50,000 validators. A larger selection returns `400`. Narrow the selection — for example, select a sub-entity instead of a whole entity — or page through it with a set of validator indices. This limit will be raised. ## OpenAPI ````yaml /v3/bundled.yaml post /api/v2/ethereum/validators/queues/consolidations 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/queues/consolidations: post: tags: - Network summary: Validator Queue Consolidation Details description: > Returns a flat, paginated list of consolidation requests involving the selected validators, whether as source (balance being merged away) or as target (balance being received). The response is not limited to requests that are still in flight: it covers the complete history of consolidations for the selected validators, back to the Pectra fork (7 May 2025). Pass `status_filter: completed` to retrieve only consolidations that have already settled. Each entry pairs a source validator with a target validator. A single validator may appear in multiple entries across both roles. Use `role_filter` to keep only the entries where a selected validator is the source, or only those where it is the target — for example, to list every validator that was ever merged into a given target validator. Which fields an entry carries depends on its `status`: | `status` | Fields set | |---|---| | `pending` | `execution_layer` — the submitting transaction | | `queued` | `source_exit_at`, `estimated_processed_at` | | `completed` | `amount`, `processed_slot` | | `rejected` | `reject_reason` | A `pending` entry becomes `queued` once the consensus layer picks the request up out of the execution-layer contract, which releases at most two consolidation requests per block. Pending and queued entries appear first, ordered by queue position (soonest processed first). Completed and rejected entries follow, ordered by submission time (most recent first). Use `status_filter` to narrow the response to a single status, e.g. only `rejected` entries. A rejected entry whose `reject_reason` is `source_equals_target` is not a failed consolidation — it is a failed switch to compounding credentials, which the consensus layer reports through the consolidation path because both requests share one contract and one structure. A common cause is asking a validator that already has `0x02` credentials to switch again. Use [/api/v2/ethereum/validators/queues/compounding-switches](/api-reference/ethereum/validators/queues/compounding-switches) to retrieve those entries as switches. Use this endpoint in combination with the queue overview at [/api/v2/ethereum/validators/queues](/api-reference/ethereum/validators/queues) for a complete picture. **Temporary restriction:** the validator selector must resolve to no more than 50,000 validators. A larger selection returns `400`. Narrow the selection — for example, select a sub-entity instead of a whole entity — or page through it with a set of validator indices. This limit will be raised. operationId: GetValidatorQueueConsolidationDetails requestBody: $ref: >- #/components/requestBodies/validatorChainCursorPageSizeConsolidationStatusFilter responses: '200': $ref: '#/components/responses/ValidatorQueueConsolidationDetail' '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: validatorChainCursorPageSizeConsolidationStatusFilter: content: application/json: schema: allOf: - $ref: '#/components/schemas/ValidatorChainCursorPageSizeBase' - type: object properties: status_filter: $ref: '#/components/schemas/ConsolidationStatusFilter' role_filter: $ref: '#/components/schemas/ConsolidationRoleFilter' required: - validator responses: ValidatorQueueConsolidationDetail: description: Successful response. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/ValidatorQueueConsolidationDetail.Data' paging: $ref: '#/components/schemas/Paging' required: - data - paging 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' ConsolidationStatusFilter: type: string nullable: true default: null description: > Filter results to a single consolidation status. If not specified, results include all statuses. - `pending`: recorded on the execution layer; not yet picked up by the consensus layer. - `queued`: included by the consensus layer; the source validator is exiting. - `completed`: balance sweep finalized. - `rejected`: rejected at consensus-layer inclusion. enum: - pending - queued - completed - rejected example: rejected x-enum-varnames: - ConsolidationStatusFilterPending - ConsolidationStatusFilterQueued - ConsolidationStatusFilterCompleted - ConsolidationStatusFilterRejected ConsolidationRoleFilter: type: string nullable: true default: null description: > Restrict results to the role the selected validators play in the consolidation. If not specified, a validator matches in either role. - `source`: only requests where a selected validator is the source — the validator that exits and whose balance is merged away. - `target`: only requests where a selected validator is the target — the validator that stays active and receives the balance. A validator is usually only ever one or the other, because a source validator exits as part of the consolidation. Use this filter when you want that guarantee rather than checking `source_validator` and `target_validator` yourself, or to avoid paging through the other role's entries for a validator that has served in both. enum: - source - target example: target x-enum-varnames: - ConsolidationRoleFilterSource - ConsolidationRoleFilterTarget ValidatorQueueConsolidationDetail.Data: type: object description: > A single consolidation request involving at least one of the selected validators. The validator that initiated the request appears as `source_validator`; the validator receiving the consolidated balance appears as `target_validator`. A queried validator may appear in either role. Consolidation is a two-phase process: - `source_exit_at`: when the source validator exits the active set and stops earning rewards. - `estimated_processed_at`: when the source validator's balance is swept to the target (withdrawable epoch). This typically follows the exit by ~27 hours (256 epochs). See the `status` field for lifecycle semantics. properties: source_validator: allOf: - $ref: '#/components/schemas/validator' description: The validator whose balance is consolidated into the target. target_validator: allOf: - $ref: '#/components/schemas/validator' description: The validator receiving the consolidated balance. status: type: string enum: - pending - queued - completed - rejected description: > Current lifecycle status of the consolidation request. - `pending`: recorded on the execution layer; the consensus layer has not yet picked it up. `execution_layer` is set. Transitions to `queued` once the request is read out of the contract, which releases at most two consolidation requests per block. - `queued`: included by the consensus layer; the source validator is exiting and its balance will be swept to the target at `estimated_processed_at`. - `completed`: balance sweep finalized; `amount` and `processed_slot` are set. - `rejected`: rejected at consensus-layer inclusion; `reject_reason` is set. example: rejected x-enum-varnames: - ValidatorQueueConsolidationDetailStatusPending - ValidatorQueueConsolidationDetailStatusQueued - ValidatorQueueConsolidationDetailStatusCompleted - ValidatorQueueConsolidationDetailStatusRejected execution_layer: allOf: - $ref: '#/components/schemas/ExecutionLayerRequestInfo' description: > Execution-layer transaction details for this request. Present for `pending` entries; null for `queued`, `completed`, and `rejected` entries (the EL↔CL linkage is not tracked once the consensus layer has processed the request). nullable: true reject_reason: allOf: - $ref: '#/components/schemas/ValidatorConsolidations.RejectReason' description: > Set when `status` is `rejected`. May be null if the rejection reason was not recognized by the server (e.g. client-specific errors or future protocol additions). nullable: true amount: allOf: - $ref: '#/components/schemas/wei' description: > Amount consolidated in wei. Set only when `status` is `completed`. Equals the source validator's effective balance at the time of the consolidation sweep — precisely `min(actual_balance, effective_balance)`. Any balance above the effective balance is not consolidated; it stays on the source and is swept to the source's own withdrawal address as a regular withdrawal. This is therefore typically less than the source's total balance. nullable: true source_exit_at: allOf: - $ref: '#/components/schemas/EstimatedWithEpoch' description: > Estimated or actual epoch when the source validator exits the active set and stops earning rewards. Set only when `status` is `queued`. Precedes `estimated_processed_at` by the withdrawal delay (~256 epochs). nullable: true estimated_processed_at: allOf: - $ref: '#/components/schemas/EstimatedWithEpoch' description: > Estimated epoch when the source validator's balance will be swept to the target. Set only when `status` is `queued`. nullable: true processed_slot: type: integer description: | The consensus layer slot in which the consolidation was finalized. Set only when `status` is `completed`. nullable: true required: - source_validator - target_validator - status 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 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' validator: type: object properties: index: allOf: - $ref: '#/components/schemas/validatorIndex' nullable: true public_key: $ref: '#/components/schemas/validatorPublicKey' ExecutionLayerRequestInfo: type: object description: >- Execution-layer transaction details for a request submitted via the EL request queue. properties: tx_hash: type: string description: The transaction hash, in 0x-prefixed hex. from_address: type: string description: The EOA address that submitted the transaction, in 0x-prefixed hex. required: - tx_hash - from_address ValidatorConsolidations.RejectReason: type: string description: Reason a consolidation request was rejected at the consensus layer. enum: - source_equals_target - full_queue - insufficient_consolidation_churn - source_unknown_pubkey - target_unknown_pubkey - source_no_execution_withdrawal_credentials - source_address_mismatch - target_not_compounding - source_inactive - target_inactive - source_exiting - target_exiting - source_too_young - source_pending_withdrawals - source_slashed example: source_inactive wei: type: string description: Amount in wei (1 ETH = 10^18 wei) pattern: ^(0|-?[1-9][0-9]*)$ EstimatedWithEpoch: type: object properties: epoch: $ref: '#/components/schemas/Epoch' description: Epoch number timestamp: $ref: '#/components/schemas/timestamp' description: Unix timestamp required: - 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 validatorIndex: description: Validator Index type: integer minimum: 0 validatorPublicKey: type: string description: Public key of a validator pattern: ^0x[a-fA-F0-9]{96}$ Epoch: type: integer minimum: 0 timestamp: type: integer minimum: 0 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. validatorIndexPublicKey: oneOf: - $ref: '#/components/schemas/validatorIndex' - $ref: '#/components/schemas/validatorPublicKey' 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. ````