> ## 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 Metadata

> Returns metadata for a set of validators, including their index, public key, deposit address, withdrawal address, entity, and sub-entity.

**Use case guide:** [Entity benchmarking](/use-cases/entity-benchmarking-overview) uses validator metadata to map validators to public entities and sub-entities.

Results are paginated with a default and maximum page size of 10.

Ideal for discovering validator associations; use the results to supply filters in other endpoints via the validator selector.

**Note:** Entity and sub-entity assignments are updated once per day.

**Premium Endpoint:** This endpoint requires a Scale or Enterprise plan.




## OpenAPI

````yaml /v3/bundled.yaml post /api/v2/ethereum/validators/metadata
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/metadata:
    post:
      tags:
        - General
      summary: 💎 Validator Metadata
      description: >
        Returns metadata for a set of validators, including their index, public
        key, deposit address, withdrawal address, entity, and sub-entity.


        **Use case guide:** [Entity
        benchmarking](/use-cases/entity-benchmarking-overview) uses validator
        metadata to map validators to public entities and sub-entities.


        Results are paginated with a default and maximum page size of 10.


        Ideal for discovering validator associations; use the results to supply
        filters in other endpoints via the validator selector.


        **Note:** Entity and sub-entity assignments are updated once per day.


        **Premium Endpoint:** This endpoint requires a Scale or Enterprise plan.
      operationId: GetValidatorMetadata
      requestBody:
        $ref: '#/components/requestBodies/validatorChainCursorPageSize'
      responses:
        '200':
          $ref: '#/components/responses/ValidatorMetadata'
        '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:
    ValidatorMetadata:
      description: Successful response.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ValidatorMetadata.ContainerList'
              - $ref: '#/components/schemas/PagingTemplate'
            description: >-
              Response containing metadata for validators including index,
              public key, deposit address, withdrawal address, entity, and
              sub-entity.
    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'
    ValidatorMetadata.ContainerList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ValidatorMetadata.Data'
      required:
        - data
    PagingTemplate:
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/Paging'
    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'
    ValidatorMetadata.Data:
      type: object
      properties:
        validator:
          $ref: '#/components/schemas/validator'
        withdrawal_credentials:
          $ref: '#/components/schemas/withdrawalCredential'
          description: >
            The withdrawal credentials for the validator, which determine where
            the validator's rewards can be withdrawn to.
        deposit_address:
          allOf:
            - $ref: '#/components/schemas/ExecutionLayerAddress'
          nullable: true
          description: |
            The Ethereum address used for the validator's deposit.
            Will be null if the deposit address is not known.
        entity:
          allOf:
            - $ref: '#/components/schemas/EntityName'
          nullable: true
          description: >
            The name of the entity associated with the validator (e.g., "Lido",
            "Coinbase").

            Will be null if the validator is not associated with any known
            entity.
        sub_entity:
          allOf:
            - $ref: '#/components/schemas/SubEntityName'
          nullable: true
          description: |
            The name of the sub-entity associated with the validator.
            Will be null if the validator is not associated with any sub-entity.
      required:
        - validator
        - withdrawal_credentials
    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
    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'
    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
    ExecutionLayerAddress:
      type: string
      pattern: ^0x[a-fA-F0-9]{40}$
      description: A standard Ethereum address (20-byte hex string with 0x prefix).
    EntityName:
      type: string
      description: The name of the entity (e.g., "Lido", "Coinbase").
    SubEntityName:
      type: string
      description: The name of the sub-entity.
    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
    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.
    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.

````