---
title: "💎 Sub Entities"
method: POST
path: "/api/v2/ethereum/entity/sub-entities"
tags: ["Entities"]
---

# 💎 Sub Entities

`POST /api/v2/ethereum/entity/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.

## Request body

- SubEntitiesOverviewRequest
  - `chain` 'mainnet' | 'hoodi' — The Ethereum chain to query.
  - `entity` string, required — The name of the entity (e.g., "Lido", "Coinbase").
  - `range` NamedEvaluationWindow, required
    - `evaluation_window` '24h' | '7d' | '30d' | '90d' | 'all_time', required — 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)
  - `cursor` string — Cursor value for pagination. See our [pagination guide](/api/pagination) for more details.
  - `page_size` integer — The number of items to return per page.
  - `sort_by` 'beaconscore' | 'net_share' | 'validator_count' — 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
  - `sort_order` 'asc' | 'desc' — The sort order for the results. - `asc`: Ascending order (lowest first) - `desc`: Descending order (highest first, default)

## Response `200`

Successful response.

- object — Response containing an overview of sub-entities for a given entity with their validator count, BeaconScore, and net share.
  - `data` SubEntitiesOverviewData[], required
    - `sub_entity` string, required — The name of the sub-entity.
    - `validator_count` integer, required — The number of validators associated with this sub-entity.
    - `beaconscore` number, float, required
    - `net_share` number, float, required
  - `last_updated` integer, required
  - `range` ResultRange, required — The range of data covered by the results, specified in slots, epochs, and Unix timestamps.
    - `slot` SlotRange, required
      - `start` integer, required — Slot by number.
      - `end` integer, required — Slot by number.
    - `epoch` EpochRange, required
      - `start` integer, required
      - `end` integer, required
    - `timestamp` TimeRange, required
      - `start` integer, required
      - `end` integer, required
  - `paging` Paging
    - `next_cursor` string — 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.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `405` — Method Not Allowed
- `429` — Rate Limit Exceeded
- `500` — Internal Server Error
- `default` — An unexpected error response.

---

[API](https://skmtc.net/beaconcha/apis/external-service-api.md) · [All operations](https://skmtc.net/beaconcha/apis/external-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/beaconcha/external-service-api/versions/ad26ad970b4e/schema)