eth_getLogs block range limits and chunked queries

eth_getLogs block range limits

When calling the JSON-RPC eth_getLogs method, the block span of a single request is calculated as toBlock − fromBlock + 1 and cannot exceed the target chain's published max_logs_block_range.

This limit varies by chain. Per-chain parameters are published through the public endpoint GET /v1/chains (chains are listed on Supported Chains). This endpoint is unauthenticated, unbilled, and unmetered. When developing client applications, query this endpoint dynamically at runtime rather than hardcoding block range limits into your code.

According to the specification, filter fields fromBlock and toBlock follow these rules:

• Defaults and null: When fromBlock or toBlock is omitted or null, it defaults to latest.
• Tag resolution: Named tags such as latest are resolved using the service's most recently polled block height.
• Unchecked conditions: Filters specifying blockHash, values that cannot be parsed, and intervals where toBlock < fromBlock are not checked for span and are forwarded to the node for handling.

Exceeding the block span limit

When a single request's block span toBlock − fromBlock + 1 exceeds the chain's max_logs_block_range, the service rejects the request with HTTP 200 and a JSON-RPC error:

• Error code: -32602
• Error message: eth_getLogs block range too large: max <N> blocks
• Billing status: This rejection is generated by the service itself and is not billed (billed: false).

Specification example request

Below is the example request from the specification exceeding the span limit (reqLogsTooWide):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_getLogs",
  "params": [
    {
      "fromBlock": "0x45a2409",
      "toBlock": "0x45a27f1"
    }
  ]
}

Specification example response

The corresponding error response example from the specification (errLogsRangeTooLarge):

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "eth_getLogs block range too large: max <N> blocks"
  }
}

Where <N> is the target chain's max_logs_block_range (published via GET /v1/chains).

In a batch request containing multiple calls, if an eth_getLogs call exceeds the block span limit, that specific item returns the -32602 error above and is not billed.

Performing chunked queries

To query logs over a large block interval, first query the target chain's max_logs_block_range, divide the target interval into contiguous chunks of [from, from + max - 1], and send sequential requests while aggregating the results.

The following examples use robinhood_mainnet to demonstrate chunked queries:

export BLOCKVECTRA_API_KEY="rgw_your_api_key"

# 1. Read max_logs_block_range from the public chains endpoint (unauthenticated, unbilled)
curl -s "https://dev-api.blockvectra.network/v1/chains"

# 2. Make a single compliant request within the chain's max_logs_block_range (toBlock - fromBlock + 1)
curl -s "https://dev-api.blockvectra.network/v1/robinhood_mainnet" \
  -H 'Content-Type: application/json' \
  -H "x-api-key: $BLOCKVECTRA_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_getLogs",
    "params": [{
      "address": "0x1111111111111111111111111111111111111111",
      "fromBlock": "0x45a2409",
      "toBlock": "0x45a246c"
    }]
  }'

Batch request considerations

If you consider packing multiple chunked queries into a single JSON-RPC batch request, keep the batch and burst capacity rules in mind:

• Batch size limit: Batch requests accept 1 to 100 calls. Submitting more than 100 calls is rejected with HTTP 200 and error code -32600 batch too large: max 100 calls (not billed).
• Single-request burst capacity: Upon arrival, the service pre-deducts the sum of full weights for calls in the request. If the sum of full weights within a single request exceeds the key's burst capacity, the service immediately returns HTTP 429 with error code -32022 request cost <N> CU exceeds burst capacity <M> CU (not billed). Waiting will not succeed; the request must be split into smaller batches.
• Insufficient bucket capacity: If the sum of full weights does not exceed burst capacity but the token bucket lacks enough available capacity, the service returns HTTP 429 with error code -32005 rate limit exceeded and Retry-After; see What is not billed: error codes and billing rules for retry and billing details.

Therefore, when performing large-scale log queries, sequential chunked queries are recommended; if batching, keep the number of calls per batch small enough so the sum of full weights remains within the burst capacity.

Related guides and billing rules

• For a comparison between eth_getLogs and the Data API transfers endpoints (address transfers and token transfers), including coverage and finality differences, see Recent node data vs indexed history: when to use eth_getLogs and when to use the transfers API.
• For full details on compute units (CU), hourly settlement, and non-billed error responses, see What is not billed: error codes and billing rules.

Next steps

• Browse the datasets directory to see every dataset BlockVectra indexes.
• See the free plan and pricing to check what your account includes.
• Log in to the console to create an API key.