> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://v3.viem.sh/api/mcp` to find what you need.

# Get Event Logs \[event.getLogs]

Returns a list of event logs matching the provided parameters.

## Usage

This example returns a list of event logs matching the provided parameters.

:::code-group
```ts twoslash [example.ts]
import { AbiEvent } from 'viem/utils'
import { client } from './viem.config'

const logs = await client.event.getLogs({
  event: AbiEvent.from(
    'event Transfer(address indexed from, address indexed to, uint256 value)',
  ),
})
// @log: [
// @log:   {
// @log:     address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2',
// @log:     args: { from: '0xd8da...', to: '0xa5cc...', value: 420n },
// @log:     blockHash: '0xabe6...01a4',
// @log:     blockNumber: 19760236n,
// @log:     data: '0x0000...01a4',
// @log:     eventName: 'Transfer',
// @log:     logIndex: 271,
// @log:     removed: false,
// @log:     topics: ['0xddf2...b3ef', '0x0000...d8da', '0x0000...a5cc'],
// @log:     transactionHash: '0xcfa5...6e93',
// @log:     transactionIndex: 145,
// @log:   },
// @log: ]
```

```ts twoslash [viem.config.ts] filename="viem.config.ts"
import { Client, http, publicActions } from 'viem'
import { mainnet } from 'viem/chains'

export const client = Client.create({
  chain: mainnet,
  transport: http(),
}).extend(publicActions())
```
:::

### Standalone Action

Call `Actions.event.getLogs` directly by passing the Client as the first argument.

:::code-group
```ts twoslash [example.ts]
import { Actions } from 'viem'
import { AbiEvent } from 'viem/utils'
import { client } from './viem.config'

const logs = await Actions.event.getLogs(client, {
  event: AbiEvent.from(
    'event Transfer(address indexed from, address indexed to, uint256 value)',
  ),
})
// @log: [
// @log:   {
// @log:     address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2',
// @log:     args: { from: '0xd8da...', to: '0xa5cc...', value: 420n },
// @log:     blockHash: '0xabe6...01a4',
// @log:     blockNumber: 19760236n,
// @log:     data: '0x0000...01a4',
// @log:     eventName: 'Transfer',
// @log:     logIndex: 271,
// @log:     removed: false,
// @log:     topics: ['0xddf2...b3ef', '0x0000...d8da', '0x0000...a5cc'],
// @log:     transactionHash: '0xcfa5...6e93',
// @log:     transactionIndex: 145,
// @log:   },
// @log: ]
```

```ts twoslash [viem.config.ts] filename="viem.config.ts"
import { Client, http } from 'viem'
import { mainnet } from 'viem/chains'

export const client = Client.create({
  chain: mainnet,
  transport: http(),
})
```
:::

## Recipes

Use a Client method or pass the Client to the standalone action.

### Fetching Logs for a Contract

Restrict logs to a single contract by passing its `address`.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'
import { AbiEvent } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const logs = await Actions.event.getLogs(client, {
  address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2', // [!code focus]
  event: AbiEvent.from(
    'event Transfer(address indexed from, address indexed to, uint256 value)',
  ),
})
```

### Filtering by Indexed Arguments

Pass `args` to filter logs by the indexed parameters of an `event`.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'
import { AbiEvent } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const logs = await Actions.event.getLogs(client, {
  event: AbiEvent.from(
    'event Transfer(address indexed from, address indexed to, uint256 value)',
  ),
  args: { // [!code focus]
    from: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045', // [!code focus]
  }, // [!code focus]
})
```

### Matching Multiple Values (OR)

Pass an array of values for an indexed argument to match any of them.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'
import { AbiEvent } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const logs = await Actions.event.getLogs(client, {
  event: AbiEvent.from(
    'event Transfer(address indexed from, address indexed to, uint256 value)',
  ),
  args: {
    from: [ // [!code focus]
      '0xd8da6bf26964af9d7eed9e03e53415d37aa96045', // [!code focus]
      '0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac', // [!code focus]
    ], // [!code focus]
  },
})
```

### Fetching Logs Within a Block Range

Pass `fromBlock` and `toBlock` to scope logs to a range of blocks.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'
import { AbiEvent } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const logs = await Actions.event.getLogs(client, {
  event: AbiEvent.from(
    'event Transfer(address indexed from, address indexed to, uint256 value)',
  ),
  fromBlock: 19760235n, // [!code focus]
  toBlock: 19760240n, // [!code focus]
})
```

### Fetching Logs for a Single Block

Pass `blockHash` to fetch logs from one block.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'
import { AbiEvent } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const logs = await Actions.event.getLogs(client, {
  blockHash: '0xabe69134e80a12f6a93d0aa18215b5b86c2fb338bae911790ca374a8716e01a4', // [!code focus]
  event: AbiEvent.from(
    'event Transfer(address indexed from, address indexed to, uint256 value)',
  ),
})
```

### Fetching Logs for Multiple Events

Pass `events` to filter and decode logs by more than one event.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'
import { AbiEvent } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const logs = await Actions.event.getLogs(client, {
  events: [ // [!code focus]
    AbiEvent.from('event Approval(address indexed owner, address indexed spender, uint256 value)'), // [!code focus]
    AbiEvent.from('event Transfer(address indexed from, address indexed to, uint256 value)'), // [!code focus]
  ], // [!code focus]
})
```

### Strictly Decoding Logs

Pass `strict: true` to only include logs whose topics and data conform exactly to `event`.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'
import { AbiEvent } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
const logs = await Actions.event.getLogs(client, {
  event: AbiEvent.from(
    'event Transfer(address indexed from, address indexed to, uint256 value)',
  ),
  strict: true, // [!code focus]
})
```

## Return Value

`readonly Log[]`

A list of event logs. When you provide `event` or `events`, each log includes decoded `args` and `eventName` values.

## Parameters

### address

* **Type:** `Address | readonly Address[]`

One or more addresses from which the logs originated.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const logs = await Actions.event.getLogs(client, {
  address: '0xfba3912ca04dd458c843e2ee08967fc04f3579c2', // [!code focus]
})
```

### args

* **Type:** Inferred from `event`.

The indexed argument values to filter the logs by. Requires `event`. Pass an array of values for a single argument to match any of them (logical OR).

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'
import { AbiEvent } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const logs = await Actions.event.getLogs(client, {
  event: AbiEvent.from(
    'event Transfer(address indexed from, address indexed to, uint256 value)',
  ),
  args: { // [!code focus]
    from: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045', // [!code focus]
    to: ['0xa5cc3c03994db5b0d9a5eedd10cabab0813678ac', '0x...'], // [!code focus]
  }, // [!code focus]
})
```

### blockHash

* **Type:** `Hex`

The hash of the block to include logs from. Mutually exclusive with `fromBlock`/`toBlock`.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const logs = await Actions.event.getLogs(client, {
  blockHash: '0xabe69134e80a12f6a93d0aa18215b5b86c2fb338bae911790ca374a8716e01a4', // [!code focus]
})
```

### event

* **Type:** `AbiEvent`

The event to filter and decode the logs by. The returned logs include the decoded `args` and `eventName`.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'
import { AbiEvent } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const logs = await Actions.event.getLogs(client, {
  event: AbiEvent.from( // [!code focus]
    'event Transfer(address indexed from, address indexed to, uint256 value)', // [!code focus]
  ), // [!code focus]
})
```

### events

* **Type:** `readonly AbiEvent[]`

A list of events to filter and decode the logs by. Mutually exclusive with `event`.

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'
import { AbiEvent } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const logs = await Actions.event.getLogs(client, {
  events: [ // [!code focus]
    AbiEvent.from('event Approval(address indexed owner, address indexed spender, uint256 value)'), // [!code focus]
    AbiEvent.from('event Transfer(address indexed from, address indexed to, uint256 value)'), // [!code focus]
  ], // [!code focus]
})
```

### fromBlock

* **Type:** `bigint | 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized'`

The block number or tag after which to include logs (inclusive).

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const logs = await Actions.event.getLogs(client, {
  fromBlock: 19760235n, // [!code focus]
  toBlock: 19760240n,
})
```

### strict

* **Type:** `boolean`
* **Default:** `false`

Whether the logs must conform exactly to the indexed and non-indexed arguments on `event`. When `false`, logs that partially conform are included (and their non-conforming `args` are omitted).

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'
import { AbiEvent } from 'viem/utils'

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const logs = await Actions.event.getLogs(client, {
  event: AbiEvent.from(
    'event Transfer(address indexed from, address indexed to, uint256 value)',
  ),
  strict: true, // [!code focus]
})
```

### toBlock

* **Type:** `bigint | 'latest' | 'earliest' | 'pending' | 'safe' | 'finalized'`

The block number or tag before which to include logs (inclusive).

```ts twoslash
import { Actions, Client, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = Client.create({ chain: mainnet, transport: http() })
// ---cut---
const logs = await Actions.event.getLogs(client, {
  fromBlock: 19760235n,
  toBlock: 19760240n, // [!code focus]
})
```

## Errors

| Error | Description |
| --- | --- |
| `AbiEvent.FilterTypeNotSupportedError` | `args` includes an indexed tuple or array, which event topic filters do not support. |
| `AbiParameters.InvalidTypeError` | `args` includes an indexed ABI type that the topic encoder does not support. |
| `Address.InvalidAddressError` | `args` includes an invalid indexed address. |
| `Hex.IntegerOutOfRangeError` | `args` includes an indexed integer outside the supported 256-bit range. |
| `Hex.SizeExceedsPaddingSizeError` | An indexed fixed-bytes value exceeds the 32-byte topic size. |