Skip to main content

​
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 per-epoch fiat values.
Need daily rewards with fiat values for up to 366 days, without code? The Income & Tax Report does it on the website.

​
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.
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.
Ranges without data: When the range ends before any of the selected validators had a validator index, or starts after the latest available day, the call answers 404 with no validator rewards data available for the requested range and validators. A selector that matches no validators gets the same answer, so check the selector once with a named window, for example "range": { "evaluation_window": "24h" }. If that call returns 200, count a range that ends before the first of your validators was activated and answers 404 as zero rewards. Any other 404 for a past range means the data is missing or not aggregated yet: retry later, and report it if it persists. Per-epoch iteration works the same way: rewards-list answers 404 for an epoch before any of the selected validators had a validator index.

​
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 at least one API call, plus one more for every further 10 validators (rewards-list returns at most 10 validators per page). 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

Tax Calculations: To value rewards at the price when you received them, you need rewards per day or per epoch. all_time and the rolling windows return a single total, so they don’t work for this, but a custom range of one UTC day returns that day’s total. 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):
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, instead of listing identifiers (results are still paginated at 10 validators per page)
  • 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.
API references: Rewards Aggregated and Rewards List.