💎 Sub Entities

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

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 and License Materials for badges and usage guidelines.

POST /api/v2/ethereum/entity/sub-entities

💎 Sub Entities

cURL

curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/entity/sub-entities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entity": "<string>",
  "range": {
    "evaluation_window": "24h"
  },
  "chain": "mainnet",
  "cursor": "",
  "page_size": 10,
  "sort_by": "net_share",
  "sort_order": "desc"
}
'

200

{
  "data": [
    {
      "sub_entity": "<string>",
      "validator_count": 1,
      "beaconscore": 0.5,
      "net_share": 0.5
    }
  ],
  "last_updated": 1,
  "range": {
    "slot": {
      "start": 1,
      "end": 1
    },
    "epoch": {
      "start": 1,
      "end": 1
    },
    "timestamp": {
      "start": 1,
      "end": 1
    }
  },
  "paging": {
    "next_cursor": "<string>"
  }
}

Authorizations

Authorization · string · header · required

Authorization header with value: Bearer YOUR_TOKEN. Refer to the API Keys section to create your API key.

Body

application/json

entity · string · required

The name of the entity to retrieve sub-entities for (e.g., "Lido", "Coinbase"). Matching is case-sensitive.

range · Fixed Window · object · required

Show child attributes

chain · enum<string> · default: mainnet

The Ethereum chain to query.

Available options: mainnet, hoodi

cursor · string · default: ""

Cursor value for pagination. See our pagination guide for more details.

page_size · integer · default: 10

The number of items to return per page.

Required range: 1 <= x <= 10

sort_by · enum<string> · default: net_share

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

Available options: beaconscore, net_share, validator_count

sort_order · enum<string> · default: desc

The sort order for the results.

• asc: Ascending order (lowest first)
• desc: Descending order (highest first, default)

Available options: asc, desc

Response

200

application/json

Successful response.

Response containing an overview of sub-entities for a given entity with their validator count, BeaconScore, and net share.

data · object[] · required

Show child attributes

last_updated · integer · required

Unix timestamp indicating when the sub-entities data was last computed. The underlying data is precomputed and updated hourly.

Required range: x >= 0

range · object · required

The range of data covered by the results, specified in slots, epochs, and Unix timestamps.

Show child attributes

paging · object

Show child attributes