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

# 💎 Operators

> Returns the entities that run validators, such as node operators and their sub-entities, with their validator count, BeaconScore®, and net share. Pass an entity's `id` or `path` as `entities.operator` in the validator selector to select its validators.

The `Unknown` row holds the validators without an operator, with the same figures, sorted among the entities, and is left out when there are none. It has no `id` or `path`, and `search` leaves it out. With the top-level entities, those with empty `ancestors`, it counts every validator once, except after an entity is merged or removed, until the next hourly count.

With `owner`, it returns only the operators that run that owner's validators, with the figures of those validators, and `Unknown` holds that owner's validators without an operator.

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

**Note:** The underlying data is precomputed and updated hourly: `last_updated` gives when the page's figures were counted, and `range` the epochs they cover. A count can land while you page through the results: the next page then sorts by the new figures, so an entity can appear twice or be missed. When `last_updated` changes between two pages, start again without a cursor. `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/operators
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/operators:
    post:
      tags:
        - Entities
      summary: 💎 Operators
      description: >
        Returns the entities that run validators, such as node operators and
        their sub-entities, with their validator count, BeaconScore®, and net
        share. Pass an entity's `id` or `path` as `entities.operator` in the
        validator selector to select its validators.


        The `Unknown` row holds the validators without an operator, with the
        same figures, sorted among the entities, and is left out when there are
        none. It has no `id` or `path`, and `search` leaves it out. With the
        top-level entities, those with empty `ancestors`, it counts every
        validator once, except after an entity is merged or removed, until the
        next hourly count.


        With `owner`, it returns only the operators that run that owner's
        validators, with the figures of those validators, and `Unknown` holds
        that owner's validators without an operator.


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


        **Note:** The underlying data is precomputed and updated hourly:
        `last_updated` gives when the page's figures were counted, and `range`
        the epochs they cover. A count can land while you page through the
        results: the next page then sorts by the new figures, so an entity can
        appear twice or be missed. When `last_updated` changes between two
        pages, start again without a cursor. `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: GetOperatorEntities
      requestBody:
        $ref: '#/components/requestBodies/operatorEntities'
      responses:
        '200':
          $ref: '#/components/responses/StakingEntities'
        '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:
    operatorEntities:
      x-go-name: OperatorEntitiesRequestBody
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OperatorEntitiesRequest'
          example:
            chain: mainnet
            owner:
              path: lido
  responses:
    StakingEntities:
      description: Successful response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StakingEntity.ContainerList'
    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:
    OperatorEntitiesRequest:
      allOf:
        - $ref: '#/components/schemas/StakingEntitiesRequest'
        - type: object
          properties:
            owner:
              description: >-
                Lists the operators that share validators with this owner. Each
                listed operator's `validator_count`, `beaconscore` and
                `net_share` then cover only the shared validators, and its
                `direct_validator_count` is null. `Unknown` then covers the
                owner's validators without an operator, and is left out when
                there are none. A merged owner lists those of the entity it was
                merged into. Any entity other than an owner answers 404.
              x-go-type-skip-optional-pointer: false
              allOf:
                - $ref: '#/components/schemas/EntityReference'
    StakingEntity.ContainerList:
      type: object
      description: >-
        Response containing the entities that match every filter, in the order
        `sort_by` and `sort_order` give.
      properties:
        data:
          type: array
          description: >-
            The entities and, unless `search` is given, the `Unknown` row of the
            validators without an entity when there are any, sorted among them.
          items:
            $ref: '#/components/schemas/StakingEntity.Data'
        last_updated:
          allOf:
            - $ref: '#/components/schemas/timestamp'
          nullable: true
          description: >-
            Unix timestamp of the hourly count behind this page's validator
            counts, `beaconscore` and `net_share`. When it changes between two
            pages, a count landed in between, and the later page sorts by its
            new figures, so start again without a cursor. Null before the
            chain's first count.
        range:
          allOf:
            - $ref: '#/components/schemas/ResultRange'
          nullable: true
          description: >-
            The epochs `beaconscore` covers, the window up to the last epoch the
            hourly count included, which `net_share` takes the balances of. Null
            before the chain's first count, and when no validator has data in
            the window.
        paging:
          $ref: '#/components/schemas/Paging'
      required:
        - data
        - last_updated
        - range
    Error:
      type: object
      properties:
        error:
          type: string
    StakingEntitiesRequest:
      type: object
      properties:
        chain:
          $ref: '#/components/schemas/Chain'
        search:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            Lists the entities whose name, or name before a rename, starts with
            this text, ignoring case. Ignoring spaces and punctuation as well,
            it also matches the start of an entity's path read with a space for
            each `/` (`Lido CSM` finds `lido/csm`), of the path's last segment,
            and of a whale's address (`0x8e60` finds `Whale_0x8e60…`). The
            `Unknown` row is left out.
          example: lido csm
        range:
          description: >-
            The window of `beaconscore`, `30d` when not given. `all_time` is not
            supported and answers 400. Every window ends at the latest hourly
            count, so the validator counts and `net_share` are the same in every
            window.
          x-go-type-skip-optional-pointer: false
          allOf:
            - $ref: '#/components/schemas/NamedEvaluationWindow'
        sort_by:
          $ref: '#/components/schemas/StakingEntitiesSortField'
        sort_order:
          $ref: '#/components/schemas/SortOrder'
        cursor:
          $ref: '#/components/schemas/Cursor'
        page_size:
          $ref: '#/components/schemas/PageSize'
    EntityReference:
      description: >-
        An entity, by `id` or by `path`. A merged entity selects the entity it
        was merged into.
      oneOf:
        - $ref: '#/components/schemas/EntityById'
        - $ref: '#/components/schemas/EntityByPath'
    StakingEntity.Data:
      type: object
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/EntityId'
          nullable: true
          description: >-
            The entity's `id`, to select it by. Null for the `Unknown` row,
            which has no entity to select.
        path:
          allOf:
            - $ref: '#/components/schemas/EntityPath'
          nullable: true
          description: >-
            The entity's `path`, its parent's path and its own segment joined by
            `/`, to select it by. Null for the `Unknown` row.
        name:
          type: string
          description: >-
            The entity's display name, or `Unknown` for the row of the
            validators without an entity.
          example: CSM
        ancestors:
          type: array
          items:
            $ref: '#/components/schemas/EntitySummary'
          example:
            - id: 7
              path: lido
              name: Lido
          description: >-
            The entities above this one, root first. Empty for a top-level
            entity and for the `Unknown` row.
        child_count:
          type: integer
          minimum: 0
          description: The number of entities directly below this one.
        validator_count:
          type: integer
          minimum: 0
          nullable: true
          description: >-
            The validators of this entity and of every entity below it, which an
            `entities` selector naming this entity selects. When the request
            body's `owner` or `operator` filter is given, only the validators
            this entity shares with that entity, which an `entities` selector
            naming both selects. For the `Unknown` row, the validators without
            an owner in `entities/owners` and without an operator in
            `entities/operators`, with the filter only that entity's. Counted
            hourly; `last_updated` gives the time. Null for an entity created
            since the latest count.
        direct_validator_count:
          type: integer
          minimum: 0
          nullable: true
          description: >-
            The validators of this entity itself, not of an entity below it, so
            `validator_count` is this count plus the `validator_count` of each
            entity directly below. Null when `validator_count` is, and when the
            request body's `owner` or `operator` filter is given.
        beaconscore:
          allOf:
            - $ref: '#/components/schemas/percent'
          nullable: true
          description: >-
            The BeaconScore® of the validators `validator_count` counts over
            `range`, how well they performed their attestation, proposal and
            sync committee duties, from 0 to 1 where 1 is perfect. Null when
            they had no duties in `range`, and when `validator_count` is null.
        net_share:
          allOf:
            - $ref: '#/components/schemas/percent'
          nullable: true
          description: >-
            The share of the network's stake held by the validators
            `validator_count` counts, by their balance at the latest hourly
            count, from 0 to 1, the same in every `range`. Null when
            `validator_count` is null.
      required:
        - id
        - path
        - name
        - ancestors
        - child_count
        - validator_count
        - direct_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 the response is `200` but no data is found, it falls back to the
        requested range, or to the full available history if no range was given.
        Some endpoints answer `404` instead when no data is found.


        For arbitrary (custom) time-range queries the queried range is expanded
        outward to whole UTC days, so the covered range may be wider than
        requested. As stated above, the reported range still reflects the data
        that was actually found — a touched UTC day with no data for the
        selected validators will not extend it.
      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
          example: eyJfc2FtcGxlX2N1cnNvciI6MTIzNDU2Nzg5MH0
    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
    StakingEntitiesSortField:
      type: string
      enum:
        - validator_count
        - beaconscore
        - net_share
      x-enum-varnames:
        - StakingEntitiesSortValidatorCount
        - StakingEntitiesSortBeaconscore
        - StakingEntitiesSortNetShare
      default: validator_count
      example: beaconscore
      description: >
        The field to order entities by, then by `path`. Entities without a value
        come last in either order.


        - `validator_count`: by number of validators (default)

        - `beaconscore`: by BeaconScore®

        - `net_share`: by share of the network's stake
    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)
    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
    EntityById:
      title: Id
      type: object
      properties:
        id:
          $ref: '#/components/schemas/EntityId'
      required:
        - id
    EntityByPath:
      title: Path
      type: object
      properties:
        path:
          $ref: '#/components/schemas/EntityPath'
      required:
        - path
    EntityId:
      type: integer
      minimum: 1
      description: >-
        An entity's `id`, as listed by
        [/api/v2/ethereum/entities/owners](/api-reference/ethereum/entities/owners)
        or
        [/api/v2/ethereum/entities/operators](/api-reference/ethereum/entities/operators).
      example: 4603
    EntityPath:
      type: string
      minLength: 1
      maxLength: 256
      description: >-
        An entity's `path`, its parent's path and its own segment joined by `/`
        (e.g. `lido/csm`). Segments are compared ignoring case, with every run
        of spaces or punctuation read as one hyphen, so `Lido / Simple DVT`
        matches `lido/simple-dvt`.
      example: lido/csm
    EntitySummary:
      type: object
      description: An entity, by its id, path and name.
      properties:
        id:
          $ref: '#/components/schemas/EntityId'
        path:
          $ref: '#/components/schemas/EntityPath'
        name:
          type: string
          description: The entity's display name.
          example: Lido
      required:
        - id
        - path
        - name
    percent:
      type: number
      format: float
      minimum: 0
      maximum: 1
      example: 0.95
    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
    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)
    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.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.