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

ScenarioApproach
Last 30 days summary (total only)Use rewards-aggregate with 30d ✅
All-time rewards (total only)Use rewards-aggregate with all_time ✅
Specific month (e.g., March 2024)Iterate epochs with rewards-list ⚠️
Tax reporting (any year)Iterate epochs with rewards-list ⚠️
Q1 rewards (Jan 1 - Mar 31)Iterate epochs with rewards-list ⚠️
Per-epoch data for fiat conversionIterate 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. 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 tier (1 req/s) and Scale plan (5 req/s):
RangeEpochsEst. API CallsEst. 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 5x the rate limit of the free tier, 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.