get_logs table function

Example

Needs RPC · RPC required

-- Recent finalized-window USDC Transfer aggregation

WITH head AS (

SELECT number AS head_block

FROM get_block($client, 'finalized')

transfers AS (

SELECT

"to",

value

FROM head,

get_logs(

$client,

'0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'::ADDRESS, -- Ethereum mainnet USDC

'event Transfer(address indexed from, address indexed to, uint256 value)',

head_block - 5,

head_block

)

SELECT

"to",

sum(value) AS raw_value,

format_units(sum(value), 6) AS usdc_value

FROM transfers

GROUP BY "to"

ORDER BY raw_value DESC;

Enable JavaScript to run this sample in the notebook. The SQL preview above is still available for reference.

API reference

Exact signatures with descriptions, requirements, inputs, returns, and examples.

get_logs(CLIENT, ADDRESS, VARCHAR) # RPC required

Decodes a human-readable event signature for one emitter without explicit block bounds.

Inputs

Name	Type	Use
`client`	CLIENT Live, pinned, or retained EVM state.	requiredpositional
`address`	ADDRESS ADDRESS, NULL::ADDRESS, or ADDRESS[] emitter filter.	requiredpositional
`event_signature`	VARCHAR Event declaration used to decode matching logs.	requiredpositional
`topic0`	BYTES32 or BYTES32[] Exact value or OR-list; the event selector for non-anonymous events.	optionalnamed
`topic3`	BYTES32 or BYTES32[] Exact value or OR-list for the third indexed parameter.	optionalnamed

Showing fewer

Result columns

Name	Type
`address`	ADDRESS Log emitter.
`block_hash`	BYTES32 Containing block hash.
`block_number`	BLOCK_NUMBER Containing block height.
`transaction_hash`	BYTES32 Emitting transaction hash.
`transaction_index`	INTEGER Transaction position in the block.

Showing fewer

Guidance

Choose a stable block window

from_block and to_block are both inclusive. block_range returns an exclusive to_block, so subtract one from its upper bound.

Use bounded finalized ranges for repeatable reads. Historical windows require a provider that retains the requested blocks.

No-range overloads are intended for limited discovery; provider range limits can reject or truncate broad queries.

SQL LIMIT trims rows after fetching; reduce RPC work with emitter, topic, and block filters.

Named parameters · RPC required

-- Recent finalized-window WETH Transfer decoding with a JSON ABI

WITH head AS (

SELECT number::BIGINT AS head_block

FROM get_block($client, 'finalized')

)

SELECT transaction_hash, log_index, "from", "to", format_units(value, 18) AS weth_amount

FROM head,

get_logs(

$client,

'0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'::ADDRESS,

'{"type":"event","name":"Transfer","inputs":[{"indexed":true,"name":"from","type":"address"},{"indexed":true,"name":"to","type":"address"},{"indexed":false,"name":"value","type":"uint256"}]}'::JSON,

head_block - 5,

head_block

);

Enable JavaScript to run this sample in the notebook. The SQL preview above is still available for reference.

Filter emitters and indexed parameters

Pass one ADDRESS, an ADDRESS[] list, or NULL::ADDRESS when the provider supports addressless log queries.

Each topic position accepts one BYTES32 value or a BYTES32[] OR-list.

For non-anonymous events, topic0 is the event selector.
topic1, topic2, and topic3 correspond to the first three indexed event parameters.
For Transfer(address indexed from, address indexed to, uint256 value), topic1 is from and topic2 is to.
Use event_signature to build topic0 and evm_abi_word to encode an indexed address.

Compare token activity

Use an ADDRESS[] overload when the same event should be compared across a small set of contracts.

Keep the window bounded and use a finalized checkpoint for a stable recent read.

USDC and USDT both use 6 decimals.
Group by the emitting address to keep results attributable to each token contract.

Named parameters · RPC required

WITH head AS (

SELECT number AS head_block

FROM get_block($client, 'finalized')

transfers AS (

SELECT

address,

value

FROM head,

get_logs(

$client,

[

'0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',

'0xdAC17F958D2ee523a2206206994597C13D831ec7'

]::ADDRESS[],

'event Transfer(address indexed from, address indexed to, uint256 value)',

head_block - 5,

head_block

)

SELECT

address AS token,

count(*) AS transfer_count,

sum(value) AS raw_value,

format_units(sum(value), 6) AS token_value

FROM transfers

GROUP BY address

ORDER BY address;

Enable JavaScript to run this sample in the notebook. The SQL preview above is still available for reference.

Topic filters

For ERC-20 Transfer(address indexed from, address indexed to, uint256 value), topic0 is the event selector, topic1 is from, and topic2 is to.

Addressless scans require a provider that supports unaddressed eth_getLogs requests.

Build topic0 with event_signature instead of copying a hash.
Build indexed address topics with evm_abi_word instead of manually padding addresses.
Use BYTES32[] for an OR filter.

Additional overloads

get_logs(CLIENT, ADDRESS, JSON) # RPC required

Decodes a JSON event ABI for one emitter without explicit block bounds.

Inputs

Name	Type	Use
`client`	CLIENT Live, pinned, or retained EVM state.	requiredpositional
`address`	ADDRESS ADDRESS, NULL::ADDRESS, or ADDRESS[] emitter filter.	requiredpositional
`event_abi`	JSON JSON event fragment used to filter and decode matching logs.	requiredpositional
`topic0`	BYTES32 or BYTES32[] Exact value or OR-list; the event selector for non-anonymous events.	optionalnamed
`topic3`	BYTES32 or BYTES32[] Exact value or OR-list for the third indexed parameter.	optionalnamed

Showing fewer

Result columns

Name	Type
`address`	ADDRESS Log emitter.
`block_hash`	BYTES32 Containing block hash.
`block_number`	BLOCK_NUMBER Containing block height.
`transaction_hash`	BYTES32 Emitting transaction hash.
`transaction_index`	INTEGER Transaction position in the block.

Showing fewer

get_logs(CLIENT, ADDRESS, VARCHAR, BIGINT) # RPC required

Decodes a human-readable event signature for one emitter from an inclusive starting block.

Inputs

Name	Type	Use
`client`	CLIENT Live, pinned, or retained EVM state.	requiredpositional
`address`	ADDRESS ADDRESS, NULL::ADDRESS, or ADDRESS[] emitter filter.	requiredpositional
`event_signature`	VARCHAR Event declaration used to decode matching logs.	requiredpositional
`from_block`	BIGINT Inclusive first block.	requiredpositional
`topic0`	BYTES32 or BYTES32[] Exact value or OR-list; the event selector for non-anonymous events.	optionalnamed

Showing fewer

Result columns

Name	Type
`address`	ADDRESS Log emitter.
`block_hash`	BYTES32 Containing block hash.
`block_number`	BLOCK_NUMBER Containing block height.
`transaction_hash`	BYTES32 Emitting transaction hash.
`transaction_index`	INTEGER Transaction position in the block.

Showing fewer

get_logs(CLIENT, ADDRESS, JSON, BIGINT) # RPC required

Decodes a JSON event ABI for one emitter from an inclusive starting block.

Inputs

Name	Type	Use
`client`	CLIENT Live, pinned, or retained EVM state.	requiredpositional
`address`	ADDRESS ADDRESS, NULL::ADDRESS, or ADDRESS[] emitter filter.	requiredpositional
`event_abi`	JSON JSON event fragment used to filter and decode matching logs.	requiredpositional
`from_block`	BIGINT Inclusive first block.	requiredpositional
`topic0`	BYTES32 or BYTES32[] Exact value or OR-list; the event selector for non-anonymous events.	optionalnamed

Showing fewer

Result columns

Name	Type
`address`	ADDRESS Log emitter.
`block_hash`	BYTES32 Containing block hash.
`block_number`	BLOCK_NUMBER Containing block height.
`transaction_hash`	BYTES32 Emitting transaction hash.
`transaction_index`	INTEGER Transaction position in the block.

Showing fewer

get_logs(CLIENT, ADDRESS, VARCHAR, BIGINT, BIGINT) # RPC required

Decodes a human-readable event signature for one emitter between inclusive block bounds.

Inputs

Name	Type	Use
`client`	CLIENT Live, pinned, or retained EVM state.	requiredpositional
`address`	ADDRESS ADDRESS, NULL::ADDRESS, or ADDRESS[] emitter filter.	requiredpositional
`event_signature`	VARCHAR Event declaration used to decode matching logs.	requiredpositional
`from_block`	BIGINT Inclusive first block.	requiredpositional
`to_block`	BIGINT Inclusive last block.	requiredpositional

Showing fewer

Result columns

Name	Type
`address`	ADDRESS Log emitter.
`block_hash`	BYTES32 Containing block hash.
`block_number`	BLOCK_NUMBER Containing block height.
`transaction_hash`	BYTES32 Emitting transaction hash.
`transaction_index`	INTEGER Transaction position in the block.

Showing fewer

get_logs(CLIENT, ADDRESS, JSON, BIGINT, BIGINT) # RPC required

Decodes a JSON event ABI for one emitter between inclusive block bounds.

Inputs

Name	Type	Use
`client`	CLIENT Live, pinned, or retained EVM state.	requiredpositional
`address`	ADDRESS ADDRESS, NULL::ADDRESS, or ADDRESS[] emitter filter.	requiredpositional
`event_abi`	JSON JSON event fragment used to filter and decode matching logs.	requiredpositional
`from_block`	BIGINT Inclusive first block.	requiredpositional
`to_block`	BIGINT Inclusive last block.	requiredpositional

Showing fewer

Result columns

Name	Type
`address`	ADDRESS Log emitter.
`block_hash`	BYTES32 Containing block hash.
`block_number`	BLOCK_NUMBER Containing block height.
`transaction_hash`	BYTES32 Emitting transaction hash.
`transaction_index`	INTEGER Transaction position in the block.

Showing fewer

get_logs(CLIENT, ADDRESS[], VARCHAR) # RPC required

Decodes a human-readable event signature for multiple emitters without explicit block bounds. Addresses are batched in groups of at most 50.

Inputs

Name	Type	Use
`client`	CLIENT Live, pinned, or retained EVM state.	requiredpositional
`addresses`	ADDRESS[] ADDRESS, NULL::ADDRESS, or ADDRESS[] emitter filter.	requiredpositional
`event_signature`	VARCHAR Event declaration used to decode matching logs.	requiredpositional
`topic0`	BYTES32 or BYTES32[] Exact value or OR-list; the event selector for non-anonymous events.	optionalnamed
`topic3`	BYTES32 or BYTES32[] Exact value or OR-list for the third indexed parameter.	optionalnamed

Showing fewer

Result columns

Name	Type
`address`	ADDRESS Log emitter.
`block_hash`	BYTES32 Containing block hash.
`block_number`	BLOCK_NUMBER Containing block height.
`transaction_hash`	BYTES32 Emitting transaction hash.
`transaction_index`	INTEGER Transaction position in the block.

Showing fewer

get_logs(CLIENT, ADDRESS[], JSON) # RPC required

Decodes a JSON event ABI for multiple emitters without explicit block bounds.

Inputs

Name	Type	Use
`client`	CLIENT Live, pinned, or retained EVM state.	requiredpositional
`addresses`	ADDRESS[] ADDRESS, NULL::ADDRESS, or ADDRESS[] emitter filter.	requiredpositional
`event_abi`	JSON JSON event fragment used to filter and decode matching logs.	requiredpositional
`topic0`	BYTES32 or BYTES32[] Exact value or OR-list; the event selector for non-anonymous events.	optionalnamed
`topic3`	BYTES32 or BYTES32[] Exact value or OR-list for the third indexed parameter.	optionalnamed

Showing fewer

Result columns

Name	Type
`address`	ADDRESS Log emitter.
`block_hash`	BYTES32 Containing block hash.
`block_number`	BLOCK_NUMBER Containing block height.
`transaction_hash`	BYTES32 Emitting transaction hash.
`transaction_index`	INTEGER Transaction position in the block.

Showing fewer

Show 4 more overloads

get_logs(CLIENT, ADDRESS[], VARCHAR, BIGINT) # RPC required

Decodes a human-readable event signature for multiple emitters from an inclusive starting block.

Inputs

Name	Type	Use
`client`	CLIENT Live, pinned, or retained EVM state.	requiredpositional
`addresses`	ADDRESS[] ADDRESS, NULL::ADDRESS, or ADDRESS[] emitter filter.	requiredpositional
`event_signature`	VARCHAR Event declaration used to decode matching logs.	requiredpositional
`from_block`	BIGINT Inclusive first block.	requiredpositional
`topic0`	BYTES32 or BYTES32[] Exact value or OR-list; the event selector for non-anonymous events.	optionalnamed

Showing fewer

Result columns

Name	Type
`address`	ADDRESS Log emitter.
`block_hash`	BYTES32 Containing block hash.
`block_number`	BLOCK_NUMBER Containing block height.
`transaction_hash`	BYTES32 Emitting transaction hash.
`transaction_index`	INTEGER Transaction position in the block.

Showing fewer

get_logs(CLIENT, ADDRESS[], JSON, BIGINT) # RPC required

Decodes a JSON event ABI for multiple emitters from an inclusive starting block.

Inputs

Name	Type	Use
`client`	CLIENT Live, pinned, or retained EVM state.	requiredpositional
`addresses`	ADDRESS[] ADDRESS, NULL::ADDRESS, or ADDRESS[] emitter filter.	requiredpositional
`event_abi`	JSON JSON event fragment used to filter and decode matching logs.	requiredpositional
`from_block`	BIGINT Inclusive first block.	requiredpositional
`topic0`	BYTES32 or BYTES32[] Exact value or OR-list; the event selector for non-anonymous events.	optionalnamed

Showing fewer

Result columns

Name	Type
`address`	ADDRESS Log emitter.
`block_hash`	BYTES32 Containing block hash.
`block_number`	BLOCK_NUMBER Containing block height.
`transaction_hash`	BYTES32 Emitting transaction hash.
`transaction_index`	INTEGER Transaction position in the block.

Showing fewer

get_logs(CLIENT, ADDRESS[], VARCHAR, BIGINT, BIGINT) # RPC required

Decodes a human-readable event signature for multiple emitters between inclusive block bounds. Addresses are batched in groups of at most 50.

Inputs

Name	Type	Use
`client`	CLIENT Live, pinned, or retained EVM state.	requiredpositional
`addresses`	ADDRESS[] ADDRESS, NULL::ADDRESS, or ADDRESS[] emitter filter.	requiredpositional
`event_signature`	VARCHAR Event declaration used to decode matching logs.	requiredpositional
`from_block`	BIGINT Inclusive first block.	requiredpositional
`to_block`	BIGINT Inclusive last block.	requiredpositional

Showing fewer

Result columns

Name	Type
`address`	ADDRESS Log emitter.
`block_hash`	BYTES32 Containing block hash.
`block_number`	BLOCK_NUMBER Containing block height.
`transaction_hash`	BYTES32 Emitting transaction hash.
`transaction_index`	INTEGER Transaction position in the block.

Showing fewer

get_logs(CLIENT, ADDRESS[], JSON, BIGINT, BIGINT) # RPC required

Decodes a JSON event ABI for multiple emitters between inclusive block bounds.

Inputs

Name	Type	Use
`client`	CLIENT Live, pinned, or retained EVM state.	requiredpositional
`addresses`	ADDRESS[] ADDRESS, NULL::ADDRESS, or ADDRESS[] emitter filter.	requiredpositional
`event_abi`	JSON JSON event fragment used to filter and decode matching logs.	requiredpositional
`from_block`	BIGINT Inclusive first block.	requiredpositional
`to_block`	BIGINT Inclusive last block.	requiredpositional

Showing fewer

Result columns

Name	Type
`address`	ADDRESS Log emitter.
`block_hash`	BYTES32 Containing block hash.
`block_number`	BLOCK_NUMBER Containing block height.
`transaction_hash`	BYTES32 Emitting transaction hash.
`transaction_index`	INTEGER Transaction position in the block.

Showing fewer

Related functions

Category and tags

Category: Chain reads
Tag: RPC

Example

API reference

Inputs

Result columns

Guidance

Choose a stable block window

Filter emitters and indexed parameters

Compare token activity

Topic filters

Additional overloads

Inputs

Result columns

Inputs

Result columns

Inputs

Result columns

Inputs

Result columns

Inputs

Result columns

Inputs

Result columns

Inputs

Result columns

Inputs

Result columns

Inputs

Result columns

Inputs

Result columns

Inputs

Result columns

Related functions

Usually used after

Usually used before

Category and tags