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

> 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`):

<CardGroup cols={2}>
  <Card title="Aggregated custom range 💎" icon="calendar-range">
    A single [Rewards Aggregated](/api-reference/ethereum/validators/rewards-aggregate) call with an explicit `timestamp`, `epoch`, or `slot` range. Requires a [Scale or Enterprise plan](https://beaconcha.in/pricing). Served at whole-UTC-day granularity.
  </Card>

  <Card title="Per-epoch iteration" icon="list">
    Iterate each epoch with the [Rewards List](/api-reference/ethereum/validators/rewards-list) endpoint. Works on any plan and returns per-epoch values — needed for finer-than-daily detail and tax reporting.
  </Card>
</CardGroup>

***

## Aggregated Custom Range 💎

With a [Scale or Enterprise plan](https://beaconcha.in/pricing), 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`.

```bash theme={null}
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 }
  }
}
'
```

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

***

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

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

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

***

## 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` ⚠️         |

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

***

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

<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 references: [Rewards Aggregated](/api-reference/ethereum/validators/rewards-aggregate) and [Rewards List](/api-reference/ethereum/validators/rewards-list).
</Tip>