# getEvents

Lists normalized ENS events across protocol versions.

## Import

```ts
import { getEvents } from "@ensforge/core/indexer";
```

## Usage

:::code-group
```ts [index.ts]
import { getEvents } from "@ensforge/core/indexer";
import { config } from "./config";

const result = await getEvents(config, {
  filter: { kinds: ["registration", "renewal"] },
  order: { direction: "desc" },
  pageSize: 20,
});
```

```ts [config.ts]
// [!include ~/snippets/core/config.ts]
```
:::

## Parameters

```ts
import type { GetEventsParametersType } from "@ensforge/core/indexer";
```

### filter

`EventFilter | undefined`

Narrows events by `name`, `namehash`, `protocols`, semantic `kinds`, `contractAddress`, block range,
or timestamp range. Bounds are inclusive. Some ENSv2 semantic event kinds require a name anchor;
unsupported combinations fail with `IndexerFilterError` before querying the endpoint.

### order

`{ direction: "asc" | "desc" } | undefined`

Orders by chain position. Defaults to descending.

### pageSize

`number | undefined`

Maximum number of items to return. It must be greater than zero and cannot exceed the
`maximumPageSize` configured for the indexer. The default is the smaller of `20` and the configured
maximum.

### cursor

`IndexerCursor | undefined`

Opaque cursor returned by the previous page. Pass it unchanged to continue the same query. A cursor
is tied to its filters, ordering, network, and enabled indexer sources; changing any of them requires
starting again without a cursor.

## Return Type

```ts
import type { GetEventsResultType } from "@ensforge/core/indexer";
```

Items are discriminated by semantic `kind` and contain normalized chain position, protocol, name identity, raw metadata, and kind-specific fields.

The result is an `IndexerPage`:

| Property               | Type                                 | Description                                                         |
| ---------------------- | ------------------------------------ | ------------------------------------------------------------------- |
| `items`                | `readonly Item[]`                    | Normalized results in deterministic cross-protocol order.           |
| `pageInfo.cursor`      | `IndexerCursor \| null`              | Cursor for the next page, or `null` when no continuation is needed. |
| `pageInfo.hasNextPage` | `boolean`                            | Whether another page is available.                                  |
| `sources`              | `readonly IndexerSourcePageStatus[]` | Per-protocol participation, block metadata, and partial failures.   |

Do not inspect or construct cursors. Persist and pass the returned value as-is.

## Protocol Sources

Compatible events from enabled ENSv1 and ENSv2 sources are normalized and merged by chain position.

## Effect

Use `.effect` when composing the action in an Effect program. The success and error channels remain
fully typed.

```ts
import { Effect } from "effect";

const program = getEvents.effect(config, parameters);

type Success = Effect.Effect.Success<typeof program>;
type Failure = Effect.Effect.Error<typeof program>;

const result = await Effect.runPromise(program);
```

## Error

```ts
import type { GetEventsError } from "@ensforge/core/indexer";
```

The Promise API rejects with the same typed failures exposed by the Effect error channel. Errors
have a stable `_tag`, `code`, and `message`; boundary errors retain their original `cause`.

See [Error Handling](/core/guides/error-handling).

## Related

* [`sdk.indexer.getEvents`](/sdk/api/indexer/history/get-events)
* [`useEvents`](/react/api/hooks/indexer/history/use-events)