> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstack.com/llms.txt
> Use this file to discover all available pages before exploring further.
# eth_getLogs | Ethereum
Ethereum API method that returns an array of all logs that match a given filter object. Logs are records of smart contract-generated events on the network and contain valuable information about transactions and smart contract interactions.
**Get your own node endpoint today**
[Start for free](https://console.chainstack.com/) and get your app to production levels immediately. No credit card required.
You can sign up with your GitHub, X, Google, or Microsoft account.
Some common use cases for `eth_getLogs` include monitoring smart contract events, tracking token transfers, and analyzing blockchain data.
## Parameters
* `object` — the filter parameters:
* `fromBlock` — (optional, default: `latest`) integer that specifies the starting block number from which the logs should be fetched.
* `toBlock` — (optional, default: `latest`) integer that specifies the ending block number until which the logs should be fetched.
* `address` — (optional) the contract address from which the logs should be fetched. It can be a single address or an array of addresses.
* `topics` — (optional) an array of `DATA` topics. The event topics for which the logs should be fetched. It can be a single topic or an array of topics.
* `blockhash` — (optional) the hash of the specific block. Limits logs to a specific block with a 32-byte hash value. It takes precedence over `fromBlock` and `toBlock`.
**Possible tags for `fromBlock` and `toBlock`**
* `latest` — the most recent block in the blockchain and the current state of the blockchain at the most recent block.
* `safe` — the block that received justification from the beacon chain. Although this block could be involved in a chain reorganization, it would necessitate either a coordinated attack by the majority of validators or an instance of severe propagation latency.
* `finalized` — the block accepted as canonical by more than 2/3 of the validators. A chain reorganization is extremely unlikely, and it would require at least 1/3 of the staked ETH to be burned.
* `earliest` — the earliest available or genesis block.
* `pending` — the pending state and transactions block. The current state of transactions that have been broadcast to the network but have not yet been included in a block.
See the [default block parameter](https://eth.wiki/json-rpc/API#the-default-block-parameter) and [How The Merge Impacts Ethereum’s Application Layer](https://blog.ethereum.org/2021/11/29/how-the-merge-impacts-app-layer).
## Response
* `array` — an array of log objects that match the specified filter or an empty array if there have been no new events since the last poll:
* `address` — the contract address from which the event originated
* `topics` — an array of 32-byte data fields containing indexed event parameters
* `data` — the non-indexed data that was emitted along with the event
* `blocknumber` — the block number in which the event was included. `null` if it is pending.
* `transactionhash` — the hash of the transaction that triggered the event. `null` if pending.
* `transactionindex` — the integer index of the transaction within the block's list of transactions. `null` if it is pending.
* `blockhash` — the hash of the block in which the event was included. `null` if it is pending.
* `logindex` — the integer identifying the index of the event within the block's list of events. `null` if pending.
* `removed` — the boolean value indicating if the event was removed from the blockchain due to a chain reorganization. `True` if the log was removed. `False` if it is a valid log.
## `eth_getLogs` code examples
Learn more about the `ChainstackProvider` in `ethers.js`: [ethers ChainstackProvider Documentation](/reference/ethersjs-chainstackprovider).
The following examples retrieve the logs of the Transfer event from the [APE token](https://etherscan.io/token/0x4d224452801aced8b2f0aebe155379bb5d594381#code) smart contract on Ethereum.
```javascript ethers.js theme={"system"}
const ethers = require("ethers");
// Create a ChainstackProvider instance for Ethereum mainnet
const chainstack = new ethers.ChainstackProvider("mainnet");
const getLogs = async () => {
const latestBlock = await chainstack.getBlockNumber();
const filter = {
fromBlock: latestBlock - 100,
toBlock: "latest",
address: "0x4d224452801ACEd8B2F0aebE155379bb5D594381",
topics: [
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
],
};
const logs = await chainstack.getLogs(filter);
console.log(logs);
};
getLogs();
```
```javascript web3.js theme={"system"}
const { Web3 } = require("web3");
const NODE_URL = "CHAINSTACK_NODE_URL";
const web3 = new Web3(NODE_URL);
async function getLogs() {
const latestBlock = await web3.eth.getBlockNumber();
const filter = {
fromBlock: latestBlock - 100n,
toBlock: 'latest',
address: '0x4d224452801ACEd8B2F0aebE155379bb5D594381',
topics: ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef']
};
const logs = await web3.eth.getPastLogs(filter);
console.log(logs);
}
getLogs();
```
```python web3.py theme={"system"}
from web3 import Web3
node_url = "CHAINSTACK_NODE_URL"
web3 = Web3(Web3.HTTPProvider(node_url))
latest_block = web3.eth.block_number
filter = {
'fromBlock': latest_block - 10,
'toBlock': 'latest',
'address': '0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270',
'topics': ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef']
}
logs = web3.eth.get_logs(filter)
print(logs)
```
Read [Tracking some Bored Apes: The Ethereum event logs tutorial](/docs/tracking-some-bored-apes-the-ethereum-event-logs-tutorial) to learn more about the `eth_getLogs` method.
## Block range limitations
While `eth_getLogs` is a powerful tool, it's crucial to understand its limitations, particularly when working with different EVM-compatible chains, as these networks often have different constraints. The `eth_getLogs` method allows you to select a range of blocks to get events from and is important to exercise proper management.
In general, `eth_getLogs` is a very resource-intensive method and although Chainstack does not pose any arbitrary limitation, some blockchain clients do, and a very large block range can impact your node's performance.
We recommend to keep the block range limit of **5,000** blocks for `eth_getLogs` on Ethereum to maintain a good balance between node and application performance.
These figures mean that the difference between the `fromBlock` and `toBlock` parameters should not exceed the given block range when querying logs.
While there are no hard limits for the Ethereum network, it's best practice to limit the range of blocks you are querying in a single request to prevent issues such as timeout errors or overly large responses.
These limitation are particularly important when working with popular smart contracts on busy blockchains, as they can return a large amount of data.
## Use case
One use case for `eth_getLogs` is to retrieve the transfer events for a specific Token ID from an ERC-721 smart contract. ERC-721 is a token standard for non-fungible tokens (NFTs), and each token transfer is recorded as an event on the blockchain. By retrieving these events, developers can track the movement of NFTs and build applications that interact with them.
The following program uses `eth_getLogs` and web3.js to track the transfers of the token number '6750' from the [BoredApeYachtClub](https://etherscan.io/token/0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d?a=7682) collection on Ethereum. This will retrieve the logs and display the address that initiated the transfer and the block number where it occurred.
```javascript index.js theme={"system"}
const { Web3 } = require("web3");
const NODE_URL = "CHAINSTACK_NODE_URL";
const web3 = new Web3(NODE_URL);
async function getTokenTransferLogs(contractAddress, tokenId) {
try {
const tokenIdHex = web3.utils.toHex(tokenId);
const tokenIdTopic = web3.utils.padLeft(tokenIdHex, 64);
const filter = {
fromBlock: 19060000n,
toBlock: 'latest',
address: contractAddress,
topics: ['0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef', null, null, tokenIdTopic]
};
const logs = await web3.eth.getPastLogs(filter);
const transferLogs = logs.map((log) => {
const topics = log.topics;
const fromAddress = topics[1];
const formattedFromAddress = `0x${fromAddress.slice(26)}`;
if (!web3.utils.toChecksumAddress(formattedFromAddress)) {
throw new Error(`${formattedFromAddress} is an invalid address`);
}
const blockNumber = log.blockNumber;
// Display a summary
console.log(`Address ${formattedFromAddress} transferred the token ${tokenId} in block ${blockNumber}.`);
return {
fromAddress: formattedFromAddress,
tokenId: tokenId,
blockNumber: blockNumber
};
});
return transferLogs;
} catch (error) {
throw new Error(`Error getting transfer logs: ${error.message}`);
}
}
async function main() {
const contractAddress = '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D';
const tokenId = 6750;
try {
const transferLogs = await getTokenTransferLogs(contractAddress, tokenId);
console.log(transferLogs);
} catch (error) {
console.error(error.message);
}
}
main();
```
This code defines an async function called `getTokenTransferLogs` which takes a `contractAddress` and a `tokenId` as input parameters.
Within the function, the `tokenId` is converted to hexadecimal format and then used to create a topic for a filter to get past logs for a specific token transfer. The `getPastLogs` function is an API that returns logs that match a certain filter.
Once the logs have been retrieved, the function loops through each log and extracts the relevant information, such as the sender's address and the block number. It also checks whether the sender's address is valid in case the parsing logic fails.
For each valid transfer log, the function logs a summary to the console and creates a transfer log object that includes the `fromAddress`, `tokenId`, and `blockNumber` properties.
The function returns an array of transfer log objects, and an exception is thrown if there are any errors.
The `main` function calls `getTokenTransferLogs` with a specific `contractAddress` and `tokenId`, and then logs the array of transfer log objects to the console. If there are any errors, an error message is logged to the console instead.
## OpenAPI
````yaml /openapi/ethereum_node_api/logs_and_events/eth_getLogs.json POST /0a9d79d93fb2f4a4b1e04695da2b77a7
openapi: 3.0.0
info:
title: Chainstack Node API
version: 1.0.0
description: This is an API for interacting with a Chainstack node.
servers:
- url: https://nd-422-757-666.p2pify.com
security: []
paths:
/0a9d79d93fb2f4a4b1e04695da2b77a7:
post:
tags:
- logs
summary: eth_getLogs
operationId: getLogs
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
method:
type: string
default: eth_getLogs
params:
type: array
items:
type: object
properties:
fromBlock:
type: string
title: from block
description: >-
The block number or tag to start searching for logs
from.
default: latest
address:
type: string
title: smart contract address
description: The contract address to retrieve the logs for.
topics:
type: array
title: topics
items:
type: string
description: >-
An array of 32-byte topics to filter for. Each topic
is treated as an OR condition.
default:
- fromBlock: latest
address: '0x4d224452801ACEd8B2F0aebE155379bb5D594381'
topics:
- >-
0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef
id:
type: integer
default: 1
jsonrpc:
type: string
default: '2.0'
responses:
'200':
description: An array of log objects matching the specified filter.
content:
application/json:
schema:
type: object
properties:
jsonrpc:
type: string
id:
type: integer
result:
type: array
items:
type: object
````