> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beaconcha.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Range Rewards

> Calculate validator rewards for any custom epoch or date range by iterating through epochs

<Warning>
  **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.
</Warning>

## 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.

<Note>
  **API Endpoint:** This guide uses [`/api/v2/ethereum/validators/rewards-list`](/api-reference/ethereum/validators/rewards-list) for per-epoch reward data.
</Note>

<Info>
  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.
</Info>

***

## When to Use Custom Range Calculation

| 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 (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 conversion | Iterate epochs with `rewards-list` ⚠️     |

<Note>
  **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](/use-cases/rewards-tax-calculations) for complete tax guidance.
</Note>

***

## Performance Considerations

The following estimates 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       |

<Tip>
  **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
</Tip>

<Tip>
  **Upgrade for Faster Processing:** [Scale](https://beaconcha.in/pricing) offers 5 req/sec, while [Enterprise plans](https://beaconcha.in/pricing) offer custom limits for high-volume needs.
</Tip>

***

## Related Resources

* [Introduction](/use-cases/rewards-introduction) — Overview and endpoint comparison
* [Tax Year Calculations](/use-cases/rewards-tax-calculations) — Specific guidance for annual tax reporting
* [Epoch & Time Zone Conversion](/use-cases/rewards-epoch-conversion) — Detailed epoch/timestamp math
* [Pagination Guide](/api/pagination) — Handling paginated responses

<Tip>
  API reference: [Rewards List](/api-reference/ethereum/validators/rewards-list).
</Tip>