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

# 💎 Sub Entities

> Returns an overview of all sub-entities associated with a given entity, including their validator count, BeaconScore, and net share.

**Use case guide:** [Entity benchmarking](/use-cases/entity-benchmarking-overview) explains how to drill from a public entity into its sub-entities and compare them with the network.

Results can be sorted by `beaconscore`, `net_share`, or `validator_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/entity/sub-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/entity/sub-entities:
    post:
      tags:
        - Entities
      summary: 💎 Sub Entities
      description: >
        Returns an overview of all sub-entities associated with a given entity,
        including their validator count, BeaconScore, and net share.


        **Use case guide:** [Entity
        benchmarking](/use-cases/entity-benchmarking-overview) explains how to
        drill from a public entity into its sub-entities and compare them with
        the network.


        Results can be sorted by `beaconscore`, `net_share`, or
        `validator_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: GetSubEntitiesOverview
      requestBody:
        $ref: '#/components/requestBodies/subEntitiesOverview'
      responses:
        '200':
          $ref: '#/components/responses/SubEntitiesOverview'
        '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:
    subEntitiesOverview:
      x-go-name: SubEntitiesOverviewRequestBody
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SubEntitiesOverviewRequest'
  responses:
    SubEntitiesOverview:
      description: Successful response.
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/SubEntitiesOverview.ContainerList'
              - $ref: '#/components/schemas/PagingTemplate'
            description: >-
              Response containing an overview of sub-entities for a given entity
              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:
    SubEntitiesOverviewRequest:
      type: object
      properties:
        chain:
          $ref: '#/components/schemas/Chain'
        entity:
          allOf:
            - $ref: '#/components/schemas/EntityName'
          description: >
            The name of the entity to retrieve sub-entities for (e.g., "Lido",
            "Coinbase").

            Matching is case-sensitive.
        range:
          $ref: '#/components/schemas/NamedEvaluationWindow'
        cursor:
          $ref: '#/components/schemas/Cursor'
        page_size:
          $ref: '#/components/schemas/PageSize'
        sort_by:
          $ref: '#/components/schemas/SubEntitiesSortField'
        sort_order:
          $ref: '#/components/schemas/SortOrder'
      required:
        - entity
        - range
    SubEntitiesOverview.ContainerList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SubEntitiesOverview.Data'
        last_updated:
          $ref: '#/components/schemas/timestamp'
          description: >
            Unix timestamp indicating when the sub-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.
    EntityName:
      type: string
      description: The name of the entity (e.g., "Lido", "Coinbase").
    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
    SubEntitiesSortField:
      type: string
      enum:
        - beaconscore
        - net_share
        - validator_count
      default: net_share
      description: |
        The field to sort sub-entities by.

        - `beaconscore`: Sort by BeaconScore (validator efficiency)
        - `net_share`: Sort by network share (default)
        - `validator_count`: Sort by number of validators
    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)
    SubEntitiesOverview.Data:
      type: object
      properties:
        sub_entity:
          $ref: '#/components/schemas/SubEntityName'
        validator_count:
          type: integer
          minimum: 0
          description: The number of validators associated with this sub-entity.
        beaconscore:
          allOf:
            - $ref: '#/components/schemas/percent'
          nullable: true
          description: >
            The BeaconScore (validator efficiency) for this sub-entity,
            representing how well the sub-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 sub-entity's share of the total network stake, expressed as a
            decimal.

            For example, 0.15 represents 15% of the network.
      required:
        - sub_entity
        - validator_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)
    SubEntityName:
      type: string
      description: The name of the sub-entity.
    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.

````