Skip to main content

​
Overview

If public entity labels do not match your internal structure, use a beaconcha.in dashboard as a private entity definition. Create one dashboard per internal entity (or one dashboard with groups), then benchmark each set against the network baseline using BeaconScore.
API Endpoints: This guide uses /api/v2/ethereum/validators/performance-aggregate (dashboard/group performance) and /api/v2/ethereum/performance-aggregate (network baseline).
See Dashboard as Private Sets for setup details and grouping workflows.

​
Why Use Dashboards as Private Entities?

Custom Entity Definitions

Define your own entities regardless of public label coverage.

Consistent Benchmarking

Compare each private set against the same network-wide BeaconScore baseline.

Group-Level Insights

Benchmark internal sub-groups (nodes, regions, client mixes) using group_id.

Operational Reporting

Produce provider and customer reports using your own internal segmentation.

​
1. Define Your Private Entity Set

Create a Validator Dashboard and add validators that should belong to one private entity. Use either:
  • dashboard_id for the full private entity set
  • dashboard_id + group_id for sub-entity benchmarking
Dashboard/group workflows are documented in Dashboard as Private Sets.

​
2. Fetch Private Entity BeaconScore

curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/validators/performance-aggregate \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chain": "mainnet",
  "validator": {
    "dashboard_id": 123
  },
  "range": {
    "evaluation_window": "30d"
  }
}
'
For subgroup benchmarking: 
{
  "validator": {
    "dashboard_id": 123,
    "group_id": 456
  }
}

​
3. Fetch Network Baseline

curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/performance-aggregate \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chain": "mainnet",
  "range": {
    "evaluation_window": "30d"
  }
}
'
Use data.beaconscore.total as the baseline.

​
4. Compare Private Entity vs Network

Compute: delta = private_entity_beaconscore - network_beaconscore Suggested interpretation:
  • delta >= +0.0025: outperforming network
  • -0.0025 < delta < +0.0025: near network average
  • delta <= -0.0025: underperforming network

​
Example: Python Script

import requests

API_KEY = "<YOUR_API_KEY>"
BASE = "https://beaconcha.in"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def post(endpoint, payload):
    resp = requests.post(f"{BASE}{endpoint}", headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    return resp.json()

window = "30d"
dashboard_id = 123

private_set = post("/api/v2/ethereum/validators/performance-aggregate", {
    "chain": "mainnet",
    "validator": {"dashboard_id": dashboard_id},
    "range": {"evaluation_window": window},
})
private_score = private_set["data"]["beaconscore"]["total"]

network = post("/api/v2/ethereum/performance-aggregate", {
    "chain": "mainnet",
    "range": {"evaluation_window": window},
})
network_score = network["data"]["beaconscore"]["total"]

delta = private_score - network_score
print(f"Private entity (dashboard {dashboard_id}): {private_score:.4f}")
print(f"Network baseline: {network_score:.4f}")
print(f"Delta: {delta:+.4f}")

​
Best Practices

Use 30d/90d Windows

Longer windows reduce short-term noise when comparing sets.

Standardize Group Semantics

Keep group naming consistent so subgroup benchmarks remain comparable.

Audit Membership

Regularly verify dashboard/group membership before publishing benchmark results.

Track Delta Trends

Store private-set vs network deltas over time for incident detection and reporting.