Custom Range Rewards

Get validator rewards for any custom epoch or date range — a single aggregated call on Scale/Enterprise, or per-epoch iteration for finer detail

Overview

There are two ways to get rewards for a specific date range that doesn’t match the predefined evaluation windows (24h, 7d, 30d, 90d, all_time):

Aggregated custom range 💎

A single Rewards Aggregated call with an explicit timestamp, epoch, or slot range. Requires a Scale or Enterprise plan. Served at whole-UTC-day granularity.

Per-epoch iteration

Iterate each epoch with the Rewards List endpoint. Works on any plan and returns per-epoch values — needed for finer-than-daily detail and tax reporting.

---

Aggregated Custom Range 💎

With a Scale or Enterprise plan, pass an explicit range to rewards-aggregate to get a single total for that period — no epoch iteration required. Specify the range by timestamp (Unix seconds), epoch, or slot.

curl --request POST \
  --url https://beaconcha.in/api/v2/ethereum/validators/rewards-aggregate \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chain": "mainnet",
  "validator": { "dashboard_id": 123 },
  "range": {
    "timestamp": { "start": 1710460800, "end": 1719705600 }
  }
}
'

Whole-UTC-day granularity: Aggregated custom ranges are rounded outward to whole UTC days — the query covers every UTC day your range touches. The response range echoes the range actually covered by the returned data. It can be wider than requested (outward day expansion) or narrower: leading or trailing days with no data for the selected validators do not extend the range. For sub-day precision or per-epoch values, use per-epoch iteration below.

---

Per-Epoch Iteration

When you need per-epoch values — finer-than-daily precision, per-epoch fiat conversion, or you’re on a plan without custom-range aggregation — iterate each epoch using the Rewards List endpoint.

API Usage Consideration: Each epoch requires a separate API call. A full month contains ~6,750 epochs, and a full year contains ~82,000 epochs. Ensure your API plan supports this volume of requests.

API Endpoint: This approach uses /api/v2/ethereum/validators/rewards-list for per-epoch reward data.

---

When to Use Each Approach

Scenario	Approach
Last 30 days summary (total only)	Use rewards-aggregate with 30d ✅
All-time rewards (total only)	Use rewards-aggregate with all_time ✅
Specific month total (e.g., March 2024) 💎	Use rewards-aggregate with a custom range ✅
Q1 total (Jan 1 - Mar 31) 💎	Use rewards-aggregate with a custom range ✅
Tax reporting (any year)	Iterate epochs with rewards-list ⚠️
Per-epoch data for fiat conversion	Iterate epochs with rewards-list ⚠️
Sub-day / exact-epoch precision	Iterate epochs with rewards-list ⚠️

Tax Calculations: Even if your validators started during the tax year, you still need per-epoch data to calculate fiat values at the time rewards were received. Neither the all_time nor a custom-range aggregate can be used for tax purposes, because both return a single summed total rather than per-epoch amounts. See Tax Year Calculations for complete tax guidance.

---

Per-Epoch Iteration Performance

These estimates apply to the per-epoch iteration approach (the aggregated custom range is a single call). They compare processing time between the Free Trial (1 req/s) and Scale plan (5 req/s):

Range	Epochs	Est. API Calls	Est. Time (Free)	Est. Time (Scale)
1 day	~225	~225	~4-5 min	~1 min
1 week	~1,575	~1,575	~25-30 min	~5-6 min
1 month	~6,750	~6,750	~2 hours	~25 min
1 quarter	~20,250	~20,250	~6 hours	~1 hour
1 year	~82,000	~82,000	~23 hours	~4-5 hours

Optimize API Usage: For large ranges, consider:

• Use dashboards and groups — Query all validators in a dashboard with a single dashboard_id or filter by group_id, reducing the need for multiple requests per epoch
• Run calculations during off-peak hours — Better API response times
• Use parallel requests — Respecting your plan’s rate limits

Upgrade for Faster Processing: Scale offers 5 req/sec, while Enterprise plans offer custom limits for high-volume needs.

---

Related Resources

• Introduction — Overview and endpoint comparison
• Tax Year Calculations — Specific guidance for annual tax reporting
• Epoch & Time Zone Conversion — Detailed epoch/timestamp math
• Pagination Guide — Handling paginated responses

API references: Rewards Aggregated and Rewards List.