# get_block

Fetches a block by decimal height, supported block tag, or block hash. The block defaults to latest and include_transactions defaults to false.

Canonical HTML: <https://determica.com/docs/functions/get_block>

- Kind: table function
- Category: [Chain reads](/docs/category/chain-reads.md)
- Tags: RPC

Fetches a block by decimal height, supported block tag, or block hash. The block defaults to latest and include_transactions defaults to false.

## Overload 1: get_block(CLIENT)

```sql
get_block(CLIENT)
```

Fetches latest with include_transactions set to false.

- Kind: table
- Execution context: Live RPC
- Behavior: Immediate Read
- Execution modes: Live Client
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: Zero Or More
- Determinism: External State
- Return shape: Table
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io

### Requirements

- attached_live_client
- rpc

### Risks

- provider_limits
- chain_reorganization

### Inputs

- `client` (CLIENT; required; positional) — Attached live CLIENT used for the RPC request.

### Result columns

Block metadata row

Returns one row. transactions contains hashes in block order for either transaction mode. transactions_full contains expanded objects only when include_transactions is true. An empty transaction array is represented as NULL in both list columns. A NULL or empty client produces a row in which every column is NULL. A NULL height, an invalid selector, a missing block or a failed RPC request raises.

- `hash` (BYTES32) — Block hash.
- `parent_hash` (BYTES32) — Parent block hash.
- `miner` (ADDRESS) — Execution-fee recipient.
- `number` (BLOCK_NUMBER) — Block height.
- `timestamp` (TIMESTAMP) — Block time in UTC.
- `size` (BIGINT) — Encoded size in bytes.
- `gas_limit` (GAS) — Block gas limit.
- `gas_used` (GAS) — Block gas consumed.
- `base_fee_per_gas` (BIGINT) — EIP-1559 base fee in Wei.
- `difficulty` (BIGINT) — Proof-of-work difficulty.
- `total_difficulty` (UINT256) — Cumulative proof-of-work difficulty.
- `transactions_root` (BYTES32) — Transaction trie root.
- `state_root` (BYTES32) — Post-block state root.
- `receipts_root` (BYTES32) — Receipt trie root.
- `logs_bloom` (BYTES256) — Receipt-log bloom filter.
- `sha3_uncles` (BYTES32) — Ommer-list hash.
- `extra_data` (BYTES) — Block-header extra data.
- `nonce` (BYTES) — Proof-of-work nonce.
- `blob_gas_used` (BIGINT) — EIP-4844 blob gas consumed.
- `excess_blob_gas` (BIGINT) — EIP-4844 excess blob gas.
- `parent_beacon_block_root` (BYTES32) — Parent beacon block root.
- `withdrawals_root` (BYTES32) — Withdrawals-list root.
- `transactions` (BYTES32[]) — Transaction hashes in block order, or NULL when the block has no transactions.
- `transactions_full` (STRUCT(hash BYTES32, block_hash BYTES32, block_number BLOCK_NUMBER, transaction_index INTEGER, "from" ADDRESS, "to" ADDRESS, "value" UINT256, gas GAS, gas_price BIGINT, max_fee_per_gas BIGINT, max_priority_fee_per_gas BIGINT, "input" BYTES, nonce BIGINT, "type" INTEGER, v INTEGER, r BYTES32, s BYTES32)[]) — Expanded transaction objects in block order when include_transactions is true, otherwise NULL.

Block metadata row. Returns one row. transactions contains hashes in block order for either transaction mode. transactions_full contains expanded objects only when include_transactions is true. An empty transaction array is represented as NULL in both list columns. A NULL or empty client produces a row in which every column is NULL. A NULL height, an invalid selector, a missing block or a failed RPC request raises.

### Examples

_Named parameters · Needs RPC · RPC required_

```sql
SELECT number, hash, timestamp
FROM get_block($client);
```

## Overload 2: get_block(CLIENT, BIGINT)

```sql
get_block(CLIENT, BIGINT)
```

Fetches a decimal block height with include_transactions set to false.

- Kind: table
- Execution context: Live RPC
- Behavior: Immediate Read
- Execution modes: Live Client
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: Zero Or More
- Determinism: External State
- Return shape: Table
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io

### Requirements

- attached_live_client
- rpc

### Risks

- provider_limits
- chain_reorganization

### Inputs

- `client` (CLIENT; required; positional) — Attached live CLIENT used for the RPC request.
- `block_number` (BIGINT; required; positional) — Non-negative BIGINT block height. NULL raises; tags and hashes are not accepted.

### Result columns

Block metadata row

Returns one row. transactions contains hashes in block order for either transaction mode. transactions_full contains expanded objects only when include_transactions is true. An empty transaction array is represented as NULL in both list columns. A NULL or empty client produces a row in which every column is NULL. A NULL height, an invalid selector, a missing block or a failed RPC request raises.

- `hash` (BYTES32) — Block hash.
- `parent_hash` (BYTES32) — Parent block hash.
- `miner` (ADDRESS) — Execution-fee recipient.
- `number` (BLOCK_NUMBER) — Block height.
- `timestamp` (TIMESTAMP) — Block time in UTC.
- `size` (BIGINT) — Encoded size in bytes.
- `gas_limit` (GAS) — Block gas limit.
- `gas_used` (GAS) — Block gas consumed.
- `base_fee_per_gas` (BIGINT) — EIP-1559 base fee in Wei.
- `difficulty` (BIGINT) — Proof-of-work difficulty.
- `total_difficulty` (UINT256) — Cumulative proof-of-work difficulty.
- `transactions_root` (BYTES32) — Transaction trie root.
- `state_root` (BYTES32) — Post-block state root.
- `receipts_root` (BYTES32) — Receipt trie root.
- `logs_bloom` (BYTES256) — Receipt-log bloom filter.
- `sha3_uncles` (BYTES32) — Ommer-list hash.
- `extra_data` (BYTES) — Block-header extra data.
- `nonce` (BYTES) — Proof-of-work nonce.
- `blob_gas_used` (BIGINT) — EIP-4844 blob gas consumed.
- `excess_blob_gas` (BIGINT) — EIP-4844 excess blob gas.
- `parent_beacon_block_root` (BYTES32) — Parent beacon block root.
- `withdrawals_root` (BYTES32) — Withdrawals-list root.
- `transactions` (BYTES32[]) — Transaction hashes in block order, or NULL when the block has no transactions.
- `transactions_full` (STRUCT(hash BYTES32, block_hash BYTES32, block_number BLOCK_NUMBER, transaction_index INTEGER, "from" ADDRESS, "to" ADDRESS, "value" UINT256, gas GAS, gas_price BIGINT, max_fee_per_gas BIGINT, max_priority_fee_per_gas BIGINT, "input" BYTES, nonce BIGINT, "type" INTEGER, v INTEGER, r BYTES32, s BYTES32)[]) — Expanded transaction objects in block order when include_transactions is true, otherwise NULL.

Block metadata row. Returns one row. transactions contains hashes in block order for either transaction mode. transactions_full contains expanded objects only when include_transactions is true. An empty transaction array is represented as NULL in both list columns. A NULL or empty client produces a row in which every column is NULL. A NULL height, an invalid selector, a missing block or a failed RPC request raises.

## Overload 3: get_block(CLIENT, VARCHAR)

```sql
get_block(CLIENT, VARCHAR)
```

Fetches a supported block tag, decimal height string, or lowercase 0x-prefixed block hash with include_transactions set to false.

- Kind: table
- Execution context: Live RPC
- Behavior: Immediate Read
- Execution modes: Live Client
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: Zero Or More
- Determinism: External State
- Return shape: Table
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io

### Requirements

- attached_live_client
- rpc

### Risks

- provider_limits
- chain_reorganization

### Inputs

- `client` (CLIENT; required; positional) — Attached live CLIENT used for the RPC request.
- `block_tag_or_hash` (VARCHAR; required; positional) — Decimal height string; latest, pending, earliest, safe, or finalized; or a 66-character block hash beginning with lowercase 0x. An empty value selects latest; NULL raises.

### Result columns

Block metadata row

Returns one row. transactions contains hashes in block order for either transaction mode. transactions_full contains expanded objects only when include_transactions is true. An empty transaction array is represented as NULL in both list columns. A NULL or empty client produces a row in which every column is NULL. A NULL height, an invalid selector, a missing block or a failed RPC request raises.

- `hash` (BYTES32) — Block hash.
- `parent_hash` (BYTES32) — Parent block hash.
- `miner` (ADDRESS) — Execution-fee recipient.
- `number` (BLOCK_NUMBER) — Block height.
- `timestamp` (TIMESTAMP) — Block time in UTC.
- `size` (BIGINT) — Encoded size in bytes.
- `gas_limit` (GAS) — Block gas limit.
- `gas_used` (GAS) — Block gas consumed.
- `base_fee_per_gas` (BIGINT) — EIP-1559 base fee in Wei.
- `difficulty` (BIGINT) — Proof-of-work difficulty.
- `total_difficulty` (UINT256) — Cumulative proof-of-work difficulty.
- `transactions_root` (BYTES32) — Transaction trie root.
- `state_root` (BYTES32) — Post-block state root.
- `receipts_root` (BYTES32) — Receipt trie root.
- `logs_bloom` (BYTES256) — Receipt-log bloom filter.
- `sha3_uncles` (BYTES32) — Ommer-list hash.
- `extra_data` (BYTES) — Block-header extra data.
- `nonce` (BYTES) — Proof-of-work nonce.
- `blob_gas_used` (BIGINT) — EIP-4844 blob gas consumed.
- `excess_blob_gas` (BIGINT) — EIP-4844 excess blob gas.
- `parent_beacon_block_root` (BYTES32) — Parent beacon block root.
- `withdrawals_root` (BYTES32) — Withdrawals-list root.
- `transactions` (BYTES32[]) — Transaction hashes in block order, or NULL when the block has no transactions.
- `transactions_full` (STRUCT(hash BYTES32, block_hash BYTES32, block_number BLOCK_NUMBER, transaction_index INTEGER, "from" ADDRESS, "to" ADDRESS, "value" UINT256, gas GAS, gas_price BIGINT, max_fee_per_gas BIGINT, max_priority_fee_per_gas BIGINT, "input" BYTES, nonce BIGINT, "type" INTEGER, v INTEGER, r BYTES32, s BYTES32)[]) — Expanded transaction objects in block order when include_transactions is true, otherwise NULL.

Block metadata row. Returns one row. transactions contains hashes in block order for either transaction mode. transactions_full contains expanded objects only when include_transactions is true. An empty transaction array is represented as NULL in both list columns. A NULL or empty client produces a row in which every column is NULL. A NULL height, an invalid selector, a missing block or a failed RPC request raises.

### Examples

_Named parameters · Needs RPC · RPC required_

```sql
-- Summarize the provider's finalized block
SELECT
  number,
  length(transactions) AS transaction_count,
  gas_used,
  gas_limit,
  round(100.0 * gas_used::DOUBLE / gas_limit::DOUBLE, 2) AS gas_utilization_pct
FROM get_block($client, 'finalized');
```

## Overload 4: get_block(CLIENT, BIGINT, BOOLEAN)

```sql
get_block(CLIENT, BIGINT, BOOLEAN)
```

Fetches a decimal block height and controls whether transactions_full contains expanded transaction objects.

- Kind: table
- Execution context: Live RPC
- Behavior: Immediate Read
- Execution modes: Live Client
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: Zero Or More
- Determinism: External State
- Return shape: Table
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io

### Requirements

- attached_live_client
- rpc

### Risks

- provider_limits
- chain_reorganization

### Inputs

- `client` (CLIENT; required; positional) — Attached live CLIENT used for the RPC request.
- `block_number` (BIGINT; required; positional) — Non-negative BIGINT block height. NULL raises; tags and hashes are not accepted.
- `include_transactions` (BOOLEAN; required; positional) — Requests expanded transaction objects when true. The default is false; NULL is also treated as false.

### Result columns

Block metadata row

Returns one row. transactions contains hashes in block order for either transaction mode. transactions_full contains expanded objects only when include_transactions is true. An empty transaction array is represented as NULL in both list columns. A NULL or empty client produces a row in which every column is NULL. A NULL height, an invalid selector, a missing block or a failed RPC request raises.

- `hash` (BYTES32) — Block hash.
- `parent_hash` (BYTES32) — Parent block hash.
- `miner` (ADDRESS) — Execution-fee recipient.
- `number` (BLOCK_NUMBER) — Block height.
- `timestamp` (TIMESTAMP) — Block time in UTC.
- `size` (BIGINT) — Encoded size in bytes.
- `gas_limit` (GAS) — Block gas limit.
- `gas_used` (GAS) — Block gas consumed.
- `base_fee_per_gas` (BIGINT) — EIP-1559 base fee in Wei.
- `difficulty` (BIGINT) — Proof-of-work difficulty.
- `total_difficulty` (UINT256) — Cumulative proof-of-work difficulty.
- `transactions_root` (BYTES32) — Transaction trie root.
- `state_root` (BYTES32) — Post-block state root.
- `receipts_root` (BYTES32) — Receipt trie root.
- `logs_bloom` (BYTES256) — Receipt-log bloom filter.
- `sha3_uncles` (BYTES32) — Ommer-list hash.
- `extra_data` (BYTES) — Block-header extra data.
- `nonce` (BYTES) — Proof-of-work nonce.
- `blob_gas_used` (BIGINT) — EIP-4844 blob gas consumed.
- `excess_blob_gas` (BIGINT) — EIP-4844 excess blob gas.
- `parent_beacon_block_root` (BYTES32) — Parent beacon block root.
- `withdrawals_root` (BYTES32) — Withdrawals-list root.
- `transactions` (BYTES32[]) — Transaction hashes in block order, or NULL when the block has no transactions.
- `transactions_full` (STRUCT(hash BYTES32, block_hash BYTES32, block_number BLOCK_NUMBER, transaction_index INTEGER, "from" ADDRESS, "to" ADDRESS, "value" UINT256, gas GAS, gas_price BIGINT, max_fee_per_gas BIGINT, max_priority_fee_per_gas BIGINT, "input" BYTES, nonce BIGINT, "type" INTEGER, v INTEGER, r BYTES32, s BYTES32)[]) — Expanded transaction objects in block order when include_transactions is true, otherwise NULL.

Block metadata row. Returns one row. transactions contains hashes in block order for either transaction mode. transactions_full contains expanded objects only when include_transactions is true. An empty transaction array is represented as NULL in both list columns. A NULL or empty client produces a row in which every column is NULL. A NULL height, an invalid selector, a missing block or a failed RPC request raises.

### Examples

_Named parameters · Needs RPC · RPC required_

```sql
-- Largest native-value transfers in the block containing the documented transaction
SELECT
  (tx).hash AS transaction_hash,
  (tx)."from" AS sender,
  (tx)."to" AS recipient,
  format_ether((tx).value) AS eth_value
FROM get_block($client, 25433824, true),
UNNEST(transactions_full) AS expanded(tx)
ORDER BY sort_key((tx).value) DESC
LIMIT 10;
```

## Overload 5: get_block(CLIENT, VARCHAR, BOOLEAN)

```sql
get_block(CLIENT, VARCHAR, BOOLEAN)
```

Fetches a supported block tag, decimal height string, or lowercase 0x-prefixed block hash and controls whether transactions_full contains expanded transaction objects.

- Kind: table
- Execution context: Live RPC
- Behavior: Immediate Read
- Execution modes: Live Client
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: Zero Or More
- Determinism: External State
- Return shape: Table
- Schema stability: Fixed
- Stability: Stable
- Side effects: network_io

### Requirements

- attached_live_client
- rpc

### Risks

- provider_limits
- chain_reorganization

### Inputs

- `client` (CLIENT; required; positional) — Attached live CLIENT used for the RPC request.
- `block_tag_or_hash` (VARCHAR; required; positional) — Decimal height string; latest, pending, earliest, safe, or finalized; or a 66-character block hash beginning with lowercase 0x. An empty value selects latest; NULL raises.
- `include_transactions` (BOOLEAN; required; positional) — Requests expanded transaction objects when true. The default is false; NULL is also treated as false.

### Result columns

Block metadata row

Returns one row. transactions contains hashes in block order for either transaction mode. transactions_full contains expanded objects only when include_transactions is true. An empty transaction array is represented as NULL in both list columns. A NULL or empty client produces a row in which every column is NULL. A NULL height, an invalid selector, a missing block or a failed RPC request raises.

- `hash` (BYTES32) — Block hash.
- `parent_hash` (BYTES32) — Parent block hash.
- `miner` (ADDRESS) — Execution-fee recipient.
- `number` (BLOCK_NUMBER) — Block height.
- `timestamp` (TIMESTAMP) — Block time in UTC.
- `size` (BIGINT) — Encoded size in bytes.
- `gas_limit` (GAS) — Block gas limit.
- `gas_used` (GAS) — Block gas consumed.
- `base_fee_per_gas` (BIGINT) — EIP-1559 base fee in Wei.
- `difficulty` (BIGINT) — Proof-of-work difficulty.
- `total_difficulty` (UINT256) — Cumulative proof-of-work difficulty.
- `transactions_root` (BYTES32) — Transaction trie root.
- `state_root` (BYTES32) — Post-block state root.
- `receipts_root` (BYTES32) — Receipt trie root.
- `logs_bloom` (BYTES256) — Receipt-log bloom filter.
- `sha3_uncles` (BYTES32) — Ommer-list hash.
- `extra_data` (BYTES) — Block-header extra data.
- `nonce` (BYTES) — Proof-of-work nonce.
- `blob_gas_used` (BIGINT) — EIP-4844 blob gas consumed.
- `excess_blob_gas` (BIGINT) — EIP-4844 excess blob gas.
- `parent_beacon_block_root` (BYTES32) — Parent beacon block root.
- `withdrawals_root` (BYTES32) — Withdrawals-list root.
- `transactions` (BYTES32[]) — Transaction hashes in block order, or NULL when the block has no transactions.
- `transactions_full` (STRUCT(hash BYTES32, block_hash BYTES32, block_number BLOCK_NUMBER, transaction_index INTEGER, "from" ADDRESS, "to" ADDRESS, "value" UINT256, gas GAS, gas_price BIGINT, max_fee_per_gas BIGINT, max_priority_fee_per_gas BIGINT, "input" BYTES, nonce BIGINT, "type" INTEGER, v INTEGER, r BYTES32, s BYTES32)[]) — Expanded transaction objects in block order when include_transactions is true, otherwise NULL.

Block metadata row. Returns one row. transactions contains hashes in block order for either transaction mode. transactions_full contains expanded objects only when include_transactions is true. An empty transaction array is represented as NULL in both list columns. A NULL or empty client produces a row in which every column is NULL. A NULL height, an invalid selector, a missing block or a failed RPC request raises.

## Guidance

### Reproducible block reads

Use an explicit block number or block hash when a query must be repeatable.

latest, pending, safe, and finalized can resolve to a different block between runs. Persist the returned number and hash when later queries must use the same snapshot.

## Related functions

- [latest_block](/docs/functions/latest_block.md) — Usually After
- [block_at](/docs/functions/block_at.md) — See Also
- [block_range](/docs/functions/block_range.md) — See Also