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

# Proposal luck

> Returns the proposal luck of a validator or a list of validators



## OpenAPI

````yaml /api/v1/bundled.yaml get /api/v1/validators/proposalLuck
openapi: 3.0.4
info:
  title: beaconcha.in API Documentation
  license:
    name: GPL-3.0
    url: https://www.gnu.org/licenses/gpl-3.0.en.html
  description: >-
    > ⚠️ No new features or endpoints will be added to V1. We recommend the [V2
    API](/api/overview) for all new projects. See the [migration
    guide](/api/v1-to-v2-migration).

    ## Introduction

    **Advanced and reliable API for accessing comprehensive Ethereum blockchain
    data.**


    - **Free Usage Policy:** The API is free to use under a fair use policy,
    with rate limits of 10 requests per minute per IP.

    - **Caching:** All responses are cached for 1 minute.

    - **Higher Usage Plans:** For higher usage plans, visit:
    [https://beaconcha.in/pricing](https://beaconcha.in/pricing). An API key is
    required to use these plans.


    ### API Key Usage

    API keys can be obtained at
    [/user/settings](https://beaconcha.in/user/settings) and must be included in
    requests either as a query string parameter or in the request header.


    #### Example: Query String Parameter

    ```bash

    curl https://beaconcha.in/api/v1/slot/1?apikey=<your_key>

    ```


    #### Example: Request Header

    ```bash

    curl -H 'apikey: <your_key>' https://beaconcha.in/api/v1/slot/1

    ```
  contact: {}
  version: '1.1'
servers:
  - url: https://beaconcha.in
    description: Ethereum mainnet
  - url: https://hoodi.beaconcha.in
    description: Hoodi Ethereum testnet
security:
  - ApiKeyAuthQuery: []
  - ApiKeyAuthHeader: []
tags:
  - name: Epoch
    description: Data related to consensus layer epochs
  - name: Slots
    description: Data related to consensus layer slots
  - name: Validators
    description: Data related to consensus layer validators
  - name: Rewards
    description: Data related to validator rewards
  - name: Sync Committees
    description: Data related to sync committees
  - name: Rocketpool
    description: Data related to the rocketpool protocol
  - name: ETH.Store®
    description: Data related to the ETH.Store® metric
  - name: Validator deposits
    description: Data related to execution layer validator deposits
  - name: Blocks
    description: Data related to execution layer blocks
  - name: Gas
    description: Data related to gas prices
  - name: Address
    description: Data related to ethereum addresses
  - name: Network
    description: Network data
  - name: Misc
    description: Miscellaneous data
  - name: User
    description: User data
  - name: Machine Metrics
    description: Submit machine, beacon-node, and validator-client monitoring metrics
paths:
  /api/v1/validators/proposalLuck:
    get:
      tags:
        - Validators
      summary: Proposal luck
      description: Returns the proposal luck of a validator or a list of validators
      parameters:
        - name: validators
          in: query
          description: Provide a comma separated list of validator indices or pubkeys
          required: true
          style: form
          explode: true
          schema:
            $ref: '#/components/schemas/primitives.indicesOrPubkeys'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/types.ApiResponse'
                  - properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/types.ApiProposalLuckResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/types.ApiErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/types.ApiErrorResponse'
components:
  schemas:
    primitives.indicesOrPubkeys:
      type: string
      description: >
        Comma-separated list (no spaces) of validator identifiers. Each
        identifier must be either:

        - A validator index as a base-10 integer (for example, 652648)

        - A BLS public key as a 96-hex-character string with or without the 0x
        prefix (case-insensitive)


        Resolution and limits:

        - The server resolves public keys to validator indices before querying
        data.

        - The total number of identifiers must not exceed the server-enforced
        limit (default 100).

        - Identifiers that cannot be parsed or resolved result in HTTP 400.
      example: 1,2,3
    types.ApiResponse:
      type: object
      description: Standard success envelope used by all API endpoints.
      properties:
        status:
          type: string
          description: >-
            HTTP-independent status of the API operation. For successful
            responses this is always "OK".
          enum:
            - OK
        data:
          description: Response payload specific to the endpoint.
          nullable: true
          x-omitempty: true
    types.ApiProposalLuckResponse:
      properties:
        average_proposal_interval:
          type: number
          description: >-
            The average slot interval between proposals for the given set of
            validators
          example: 1115586.53125
        next_proposal_estimate_ts:
          type: integer
          description: The estimated timestamp of the next proposal
          example: 1767606011
        proposal_luck:
          type: number
          description: The proposal luck for the given set of validators as a percentage
          example: 0.43039603829089507
        time_frame_name:
          type: string
          description: The timeframe for which the luck is calculated
          example: year
    types.ApiErrorResponse:
      type: object
      description: Standard error envelope returned when a request fails.
      properties:
        status:
          type: string
          description: >-
            Human-readable error indicator and message. The value begins with
            "ERROR:" followed by details.
          example: 'ERROR: <Message>'
        data:
          type: string
          description: Optional additional context for the error. Null in most cases.
          nullable: true
          default: null
  securitySchemes:
    ApiKeyAuthQuery:
      type: apiKey
      in: query
      name: apikey
      description: ''
    ApiKeyAuthHeader:
      type: apiKey
      in: header
      name: apikey
      description: ''

````