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

# 💎 Overview

> Returns an overview of all entities with their validator count, BeaconScore, and net share.

**Use case guide:** [Entity benchmarking](/use-cases/entity-benchmarking-overview) explains how to rank entities and compare an operator with the network baseline.

Results can be sorted by `beaconscore`, `net_share`, `validator_count`, or `sub_entity_count` in ascending or descending order.
By default, results are sorted by `net_share` in descending order.

**Note:** The underlying data is precomputed and updated hourly. `all_time` evaluation window is not supported for this endpoint.

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

**Attribution Required:** If you display BeaconScore data publicly, you must include appropriate attribution. See our [BeaconScore License](/legal/beaconscore-license) and [License Materials](/legal/license-materials) for badges and usage guidelines.




## OpenAPI

````yaml /v3/bundled.yaml post /api/v2/ethereum/entities
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/entities:
    post:
      tags:
        - Entities
      summary: 💎 Overview
      description: >
        Returns an overview of all entities with their validator count,
        BeaconScore, and net share.


        **Use case guide:** [Entity
        benchmarking](/use-cases/entity-benchmarking-overview) explains how to
        rank entities and compare an operator with the network baseline.


        Results can be sorted by `beaconscore`, `net_share`, `validator_count`,
        or `sub_entity_count` in ascending or descending order.

        By default, results are sorted by `net_share` in descending order.


        **Note:** The underlying data is precomputed and updated hourly.
        `all_time` evaluation window is not supported for this endpoint.


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


        **Attribution Required:** If you display BeaconScore data publicly, you
        must include appropriate attribution. See our [BeaconScore
        License](/legal/beaconscore-license) and [License
        Materials](/legal/license-materials) for badges and usage guidelines.
      operationId: GetEntitiesOverview
      requestBody:
        $ref: '#/components/requestBodies/entitiesOverview'
      responses:
        '200':
          $ref: '#/components/responses/EntitiesOverview'
        '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:
    entitiesOverview:
      x-go-name: EntitiesOverviewRequestBody
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EntitiesOverviewRequest'
  responses:
    EntitiesOverview:
      description: Successful response.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/EntitiesOverview.ContainerList'
              - $ref: '#/components/schemas/PagingTemplate'
            description: >-
              Response containing an overview of entities with their validator
              count, BeaconScore, and net share.
    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:
    EntitiesOverviewRequest:
      type: object
      properties:
        chain:
          $ref: '#/components/schemas/Chain'
        range:
          $ref: '#/components/schemas/NamedEvaluationWindow'
        cursor:
          $ref: '#/components/schemas/Cursor'
          description: >
            Opaque continuation token from a previous response.

            For machine metrics this token stores series-specific continuation
            state for `system_metrics`, `validator_metrics`,

            and `node_metrics` rather than a single shared list position.
        page_size:
          $ref: '#/components/schemas/PageSize'
          description: >-
            Number of items to return per metric array. Defaults to `10` when
            omitted.
        sort_by:
          $ref: '#/components/schemas/EntitiesSortField'
        sort_order:
          $ref: '#/components/schemas/SortOrder'
      required:
        - range
    EntitiesOverview.ContainerList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/EntitiesOverview.Data'
        last_updated:
          $ref: '#/components/schemas/timestamp'
          description: |
            Unix timestamp indicating when the entities data was last computed.
            The underlying data is precomputed and updated hourly.
        range:
          $ref: '#/components/schemas/ResultRange'
      required:
        - data
        - last_updated
        - range
    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.
    NamedEvaluationWindow:
      type: object
      title: Fixed Window
      properties:
        evaluation_window:
          $ref: '#/components/schemas/EvaluationWindow'
      required:
        - evaluation_window
    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
    EntitiesSortField:
      type: string
      enum:
        - beaconscore
        - net_share
        - validator_count
        - sub_entity_count
      default: net_share
      description: |
        The field to sort entities by.

        - `beaconscore`: Sort by BeaconScore (validator efficiency)
        - `net_share`: Sort by network share (default)
        - `validator_count`: Sort by number of validators
        - `sub_entity_count`: Sort by number of sub-entities
    SortOrder:
      type: string
      enum:
        - asc
        - desc
      default: desc
      description: |
        The sort order for the results.

        - `asc`: Ascending order (lowest first)
        - `desc`: Descending order (highest first, default)
    EntitiesOverview.Data:
      type: object
      properties:
        entity:
          $ref: '#/components/schemas/EntityName'
        validator_count:
          type: integer
          minimum: 0
          description: The number of validators associated with this entity.
        sub_entity_count:
          type: integer
          minimum: 0
          description: The number of sub-entities associated with this entity.
        beaconscore:
          allOf:
            - $ref: '#/components/schemas/percent'
          nullable: true
          description: >
            The BeaconScore (validator efficiency) for this entity, representing
            how well the entity's validators perform their duties.

            Value is between 0.0 and 1.0, where 1.0 represents perfect
            performance.
        net_share:
          $ref: '#/components/schemas/percent'
          description: >
            The entity's share of the total network stake, expressed as a
            decimal.

            For example, 0.15 represents 15% of the network.
      required:
        - entity
        - validator_count
        - sub_entity_count
        - beaconscore
        - net_share
    timestamp:
      type: integer
      minimum: 0
    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
    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
    EvaluationWindow:
      type: string
      enum:
        - 24h
        - 7d
        - 30d
        - 90d
        - all_time
      description: >
        The evaluation window for aggregating metrics. All windows except
        `all_time` are **rolling periods**—continuously moving time windows that
        always end at the current epoch.


        Rolling windows update every epoch (~6.4 minutes), so the data always
        reflects the most recent period. For example, `30d` returns rewards from
        exactly 30 days ago until now, not a fixed calendar month.


        - `24h`: Last 24 hours (rolling)

        - `7d`: Last 7 days (rolling)

        - `30d`: Last 30 days (rolling)

        - `90d`: Last 90 days (rolling)

        - `all_time`: Since validator activation (not rolling)
    EntityName:
      type: string
      description: The name of the entity (e.g., "Lido", "Coinbase").
    percent:
      type: number
      format: float
      minimum: 0
      maximum: 1
    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
    Slot:
      type: integer
      minimum: 0
      description: Slot by number.
    Epoch:
      type: integer
      minimum: 0
  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.

````