debug_traceBlockByNumber

debug_traceBlockByNumber runs a full trace over one Ethereum block (chain ID 1, native coin ETH) that you select by height instead of by hash. Pass a hex block number, or one of latest, earliest, pending, safe, or finalized — the last two map onto Gasper's justified and finalized checkpoints, which is the dependable way to trace heights that can no longer be reorged. For each transaction in the selected block the node re-executes it on the EVM and emits a per-transaction opcode trace, ordered as they appear on chain. Send requests to https://ethereum.therpc.io/YOUR_API_KEY. Re-running an entire block is expensive, so this needs a debug-enabled archive node for any height beyond the recent state window.

Use cases

Audit every state transition in a block in one shot — convenient for indexers that walk the chain height by height and need each block's full execution rather than one transaction at a time.
Pull the complete call graph of a block for MEV research with callTracer, then study how searchers ordered their transactions within the 12-second slot.
Compare the gas profiles of all transactions in a block to flag outliers — the one swap that burned ten times the gas of its neighbors usually points at a pricing bug or an unusually deep call path.

Parameters

#	Name	Type	Required	Description
1	`blockNumber`	string	Yes	Block to trace.
2	`options`	object	No	Same tracer configuration object as debug_traceTransaction.

Response

Type	Description
array	Array of per-transaction trace results in block order. Each element has the same shape as debug_traceTransaction output for the active tracer.

Example request

1curl https://ethereum.therpc.io/YOUR_API_KEY \
2  -X POST \
3  -H "Content-Type: application/json" \
4  -d '{
5    "jsonrpc": "2.0",
6    "method": "debug_traceBlockByNumber",
7    "params": [
8        "latest",
9        {}
10      ],
11    "id": 1
12  }'

Try it live in the Ethereum playground.

Errors & troubleshooting

Code	Message	Cause
`-32601`	`Method not found`	debug namespace not enabled on the node.
`-32602`	`Invalid params`	Block number is malformed or not a recognized tag.
`-32000`	`block not found`	Block does not exist or archive state is unavailable for that number.

Common pitfalls

Tracing a block means replaying every transaction in it. A packed mainnet block can take minutes and, with the default struct logger, return gigabytes — reach for callTracer unless you truly need opcode detail.
Archive state is required for historical heights. A pruned full node keeps only the recent trie, so anything older returns block not found.
Tags like latest resolve at request time and can race a freshly proposed block. For results that won't shift under a reorg, trace at finalized instead — once a checkpoint finalizes (~12.8 minutes), the block is locked in.

Supported networks

Mainnet — Chain ID: 1
Sepolia — Chain ID: 11155111