> ## 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. # Withdrawal Slots > Returns a list of withdrawal events for your selected validators. Use this endpoint to quickly identify all relevant withdrawals for your validator set. You can combine this endpoint with: - Withdrawal detail from slot: [v2/ethereum/slot/withdrawals](/api-reference/ethereum/slot/withdrawals) - Consensus slot information: [v2/ethereum/slot](/api-reference/ethereum/slot/overview) Results can be filtered by a time range. ## OpenAPI ````yaml /v3/bundled.yaml post /api/v2/ethereum/validators/withdrawal-slots 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/withdrawal-slots: post: tags: - Validator summary: Withdrawal Slots description: > Returns a list of withdrawal events for your selected validators. Use this endpoint to quickly identify all relevant withdrawals for your validator set. You can combine this endpoint with: - Withdrawal detail from slot: [v2/ethereum/slot/withdrawals](/api-reference/ethereum/slot/withdrawals) - Consensus slot information: [v2/ethereum/slot](/api-reference/ethereum/slot/overview) Results can be filtered by a time range. operationId: GetValidatorWithdrawalSlots requestBody: $ref: >- #/components/requestBodies/ValidatorChainOptionalStartEndCursorPageSizeStageFilter responses: '200': $ref: '#/components/responses/ValidatorWithdrawals' '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: ValidatorChainOptionalStartEndCursorPageSizeStageFilter: content: application/json: schema: $ref: >- #/components/schemas/ValidatorChainOptionalStartEndCursorPageSizeStageFilter responses: ValidatorWithdrawals: description: Successful response. content: application/json: schema: allOf: - $ref: '#/components/schemas/ValidatorWithdrawals.ContainerList' - $ref: '#/components/schemas/PagingRangeTemplate' description: >- Response containing detailed withdrawal information of the validators. 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: ValidatorChainOptionalStartEndCursorPageSizeStageFilter: allOf: - $ref: '#/components/schemas/ValidatorChainCursorPageSizeBase' - $ref: '#/components/schemas/rangeNamedNullable' - type: object properties: stage_filter: $ref: '#/components/schemas/QueueTypeFilter' required: - validator ValidatorWithdrawals.ContainerList: type: object properties: data: type: array items: $ref: '#/components/schemas/ValidatorWithdrawals.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 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' rangeNamedNullable: type: object properties: range: $ref: '#/components/schemas/timeRangeSelectorNullable' QueueTypeFilter: type: array nullable: true description: > Deposits and withdrawals progress through multiple stages as they move from the execution layer (EL) to the consensus layer (CL) and back. Each stage is associated with a specific slot, and filtering by these stages helps you pinpoint exactly when an event was queued, processed, or credited. **Stages:** 1. `execution_layer_queued` – The request is signaled on the execution layer. 2. `execution_layer_processed` – The request is dequeued on the execution layer and enters the consensus layer queue or is immediately rejected. 3. `consensus_layer_queued` – The request is recognized by the consensus layer, but not yet processed. 4. `consensus_layer_processed` – The request is fully processed by the consensus layer and the funds are credited to the target validator or withdrawal address; or rejected. **How to use this filter:** - Pass one or more stages as an array to include events observed in any of the selected stages. Omit the field (or pass an empty array) to include all stages. - If you just submitted a deposit or withdrawal on-chain, look for **execution_layer_queued** (initial signal), then **consensus_layer_queued** (picked up by CL), and finally **consensus_layer_processed** (final credit). - To find when a deposit is *credited* to your validator, filter by **consensus_layer_processed**. - To find when a withdrawal is *credited* to your address, also filter by **consensus_layer_processed**. - If the request is valid, **execution_layer_processed** and **consensus_layer_queued** will occur in the same slot, while **consensus_layer_processed** will occur in a later slot. - If the request is rejected, **execution_layer_processed** and **consensus_layer_processed** will occur in the same slot, while **consensus_layer_queued** will not occur at all. **Tip:** Use the appropriate stages to track the exact point in the lifecycle of your deposit or withdrawal, depending on whether you care about when it was signaled, queued, or actually credited. items: $ref: '#/components/schemas/QueueType' example: - consensus_layer_processed ValidatorWithdrawals.Data: type: object properties: slot: $ref: '#/components/schemas/Slot' x-sortable: true observed_stages: type: array items: $ref: '#/components/schemas/QueueType' finality: $ref: '#/components/schemas/FinalityParams' required: - slot - observed_stages - 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 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' timeRangeSelectorNullable: description: > Specify a time range using either Unix timestamps or epoch numbers. If left null, the API will query the entire available history of the selected validators. nullable: true default: null oneOf: - $ref: '#/components/schemas/timeRangeSelectorTime' - $ref: '#/components/schemas/timeRangeSelectorEpoch' - $ref: '#/components/schemas/timeRangeSelectorSlot' QueueType: type: string enum: - execution_layer_queued - execution_layer_processed - consensus_layer_queued - consensus_layer_processed Slot: type: integer minimum: 0 description: Slot by number. FinalityParams: 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 - 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 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 timeRangeSelectorTime: type: object title: Unix Timestamp description: Range provided via Unix timestamp (inclusive) properties: timestamp: $ref: '#/components/schemas/timeRangeStartEnd' required: - timestamp timeRangeSelectorEpoch: type: object title: Epoch description: Range provided via epoch number properties: epoch: $ref: '#/components/schemas/epochRangeStartEnd' required: - epoch timeRangeSelectorSlot: type: object title: Slot description: Range provided via slot number properties: slot: $ref: '#/components/schemas/slotRangeStartEnd' required: - slot 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. timeRangeStartEnd: type: object description: Unix timestamp range (inclusive) properties: start: $ref: '#/components/schemas/timestamp' example: 0 description: Start Unix Timestamp end: $ref: '#/components/schemas/timestamp' example: 2147483647 description: End Unix Timestamp required: - start - end epochRangeStartEnd: type: object description: Epoch range (inclusive) properties: start: $ref: '#/components/schemas/EpochSelector' description: Start Epoch end: $ref: '#/components/schemas/EpochSelector' description: End Epoch required: - start - end slotRangeStartEnd: type: object description: Slot range (inclusive) properties: start: $ref: '#/components/schemas/SlotSelector' description: Start Slot end: $ref: '#/components/schemas/SlotSelector' description: End Slot validatorIndexPublicKey: oneOf: - $ref: '#/components/schemas/validatorIndex' - $ref: '#/components/schemas/validatorPublicKey' EpochSelector: description: | Specify an epoch using one of the following methods. - epoch number - View: "latest", "finalized" oneOf: - $ref: '#/components/schemas/EpochByNumber' - $ref: '#/components/schemas/EpochByChainView' SlotSelector: description: | Specify a slot using one of the following methods. - Slot number - Consensus layer block root - View: "latest", "finalized" oneOf: - $ref: '#/components/schemas/SlotByNumber' - $ref: '#/components/schemas/SlotByConsensusLayerBlockRoot' - $ref: '#/components/schemas/SlotByChainView' default: latest validatorIndex: description: Validator Index type: integer minimum: 0 validatorPublicKey: type: string description: Public key of a validator pattern: ^0x[a-fA-F0-9]{96}$ EpochByNumber: title: Number type: object properties: number: $ref: '#/components/schemas/Epoch' required: - number EpochByChainView: title: View type: object properties: view: allOf: - $ref: '#/components/schemas/ChainView' description: > - "latest": Refers to the most recent epoch, which may not yet be finalized. - "finalized": Refers to the latest epoch that has been finalized and is not subject to change. required: - view SlotByNumber: title: Number type: object properties: number: $ref: '#/components/schemas/Slot' required: - number SlotByConsensusLayerBlockRoot: title: Root type: object properties: root: $ref: '#/components/schemas/ConsensusLayerBlockRoot' required: - root SlotByChainView: title: View type: object properties: view: allOf: - $ref: '#/components/schemas/ChainView' description: > - "latest": Refers to the most recent slot, which may be subject to reorganization. - "finalized": Refers to the latest slot that has been finalized and is not subject to change. required: - view ChainView: type: string enum: - latest - finalized description: > - "latest": Refers to the most recent block, which may be subject to reorganization. - "finalized": Refers to the latest block that has been finalized and is not subject to change. ConsensusLayerBlockRoot: type: string pattern: ^0x[a-fA-F0-9]{64}$ description: A 32-byte block root represented as a hex string with 0x prefix. 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. ````