Skip to main content
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.We are developing endpoints designed to streamline the retrieval of summarized data for user-defined periods. Manually summing up rewards epoch-by-epoch doesn’t scale well for many validators over long timeframes.

​
Overview

When you need rewards for a specific date range that doesn’t match the predefined evaluation windows (24h, 7d, 30d, 90d, all_time), you must iterate through each epoch using the Rewards List endpoint.
API Endpoint: This guide uses /api/v2/ethereum/validators/rewards-list for per-epoch reward data.
The Rewards Aggregated endpoint only supports rolling periods and all_time. For custom historical ranges (like “March 15 to June 30, 2024”), you must use the Rewards List endpoint.

​
When to Use Custom Range Calculation

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. The all_time aggregate cannot be used for tax purposes. See Tax Year Calculations for complete tax guidance.

​
Performance Considerations

The following estimates compare processing time between the Free Trial (1 req/s) and Scale plan (5 req/s):
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.
For detailed API specifications, see the Rewards (CL + EL) section in the V2 API Docs sidebar.