# indexer.getHistory

> For the complete documentation index, see [llms.txt](https://ensforge.com/llms.txt).

Reads the full history of a name, or of every name an address is related to. Options, result, errors and examples for indexer.getHistory.

Source: https://ensforge.com/docs/reference/sdk/indexer/get-history

<ApiMeta kind="Read" stability="stable" since="1.0.0" source="packages/sdk/src/actions/indexer/getHistory/index.ts#L58" batchable />

Reads the full history of a name, or of every name an address is related to.

## When to use [#when-to-use]

Use to show an activity feed for a name or an account, back to its first event.

## Details [#details]

- Events use the same `type` and `action` vocabulary as `event.get`, which reads recent events
  straight from the chain.
- Newest first by default (`order: "asc"` for oldest first); each event carries its details
  (`data`) unless `includeData: false`.
- `scope` selects the name's own events, its registrations' events, or both (default).

## Signature [#signature]

```ts
function getHistory(
  client: Like,
  options: getHistory.Options,
): Promise<getHistory.ReturnType>
```

Call it as `ens.indexer.getHistory(options)` on a client, or `Actions.indexer.getHistory(client, options)`.

`indexer.getHistory.request(options)` builds a deferred read for `Actions.batch`. See [Look up many at once](/docs/sdk/look-up-many-at-once).

In React, use [`useNameHistory`](/docs/reference/react/use-name-history).

## Parameters [#parameters]

With `name`:

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `limit` | `number` |  | Rows per page, 1–200. @default 50 |
| `cursor` | `string` |  | The previous page's `cursor`. |
| `includeTotal` | `boolean` |  | Count every row (`totalCount`); slower. |
| `types` | `readonly EventType[]` |  |  |
| `excludeTypes` | `readonly EventType[]` |  |  |
| `recordKey` | `string` |  | Record key, e.g. `avatar`, `text:url` or `addr:60`. |
| `from` | `bigint \| Date` |  | Inclusive time bounds (Unix seconds or dates). |
| `to` | `bigint \| Date` |  |  |
| `order` | `"asc" \| "desc"` | `"desc"` | Sort direction. |
| `includeData` | `boolean` |  | Include each event's details (`data`, `action`). @default true |
| `namespace` | `Namespace` |  | Namespace; inferred from the name, or every namespace for an address. |
| `scope` | `"name" \| "registration" \| "both"` |  | Name events, registration events, or both. @default "both" |
| `name` (required) | `string` |  | The name whose history to read. |
| `includeChildRegistrations` | `boolean` |  | Also the registrations of its children. |

With `address`:

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `limit` | `number` |  | Rows per page, 1–200. @default 50 |
| `cursor` | `string` |  | The previous page's `cursor`. |
| `includeTotal` | `boolean` |  | Count every row (`totalCount`); slower. |
| `types` | `readonly EventType[]` |  |  |
| `excludeTypes` | `readonly EventType[]` |  |  |
| `recordKey` | `string` |  | Record key, e.g. `avatar`, `text:url` or `addr:60`. |
| `from` | `bigint \| Date` |  | Inclusive time bounds (Unix seconds or dates). |
| `to` | `bigint \| Date` |  |  |
| `order` | `"asc" \| "desc"` | `"desc"` | Sort direction. |
| `includeData` | `boolean` |  | Include each event's details (`data`, `action`). @default true |
| `namespace` | `Namespace` |  | Namespace; inferred from the name, or every namespace for an address. |
| `scope` | `"name" \| "registration" \| "both"` |  | Name events, registration events, or both. @default "both" |
| `address` (required) | `string` |  | The address whose names' history to read. |
| `relation` | `readonly ("owner" \| "manager" \| "roleHolder")[]` |  | Relations to follow. @default ["owner", "manager", "roleHolder"] |

Also takes the [read options](/docs/reference/sdk/client#read-options).

## Returns [#returns]

Resolves to `Page<IndexedEvent>`. One page of events.

## Errors [#errors]

| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME), [`INVALID_ADDRESS`](/docs/reference/errors/INVALID_ADDRESS) | invalid input. |
| [`NotFoundError`](/docs/reference/errors/not-found-error) | [`INDEXER_NOT_FOUND`](/docs/reference/errors/INDEXER_NOT_FOUND) | the indexer has no such name. |
| [`ConfigError`](/docs/reference/errors/config-error) | [`INDEXER_NOT_CONFIGURED`](/docs/reference/errors/INDEXER_NOT_CONFIGURED) | the client has no indexer. |
| [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNSUPPORTED`](/docs/reference/errors/INDEXER_UNSUPPORTED) | the indexer does not serve the query or its namespace. |
| [`IndexerError`](/docs/reference/errors/indexer-error) | [`INDEXER_UNAVAILABLE`](/docs/reference/errors/INDEXER_UNAVAILABLE), [`INDEXER_RATE_LIMITED`](/docs/reference/errors/INDEXER_RATE_LIMITED), [`INDEXER_BEHIND`](/docs/reference/errors/INDEXER_BEHIND), [`INDEXER_REQUEST_REJECTED`](/docs/reference/errors/INDEXER_REQUEST_REJECTED), [`INDEXER_RESPONSE_INVALID`](/docs/reference/errors/INDEXER_RESPONSE_INVALID) | the indexer is unavailable, rate limiting, behind, rejects the request or answers unexpectedly. |

It can also fail with the errors every read can (`Errors.CommonError`: `ConfigError`, `ContractRevertError`, `InternalError`, `NetworkError`).

See [How errors work](/docs/sdk/errors-explained).

## Examples [#examples]

<Tabs groupId="api" items={["Client","Standalone","Effect"]} persist>
<Tab>
```ts title="Reading a name's history"
const page = await ens.indexer.getHistory({ name: "nick.eth" })
```
</Tab>

<Tab>
```ts title="Reading an address's history with a standalone call"
import { Actions } from "@ensforge/sdk"

const page = await Actions.indexer.getHistory(ens, { address, types: ["transfer"] })
```
</Tab>

<Tab>
```ts title="Reading record changes in an Effect program"
import { Actions } from "@ensforge/sdk/effect"

const page = yield* Actions.indexer.getHistory(ens, { name: "nick.eth", recordKey: "avatar" })
```
</Tab>
</Tabs>

## Example response [#example-response]

Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does.

```ts
await ens.indexer.getHistory({ name: "ens.eth", namespace: "ens", limit: 3 })
```

```json
{
  "asOf": {
    "chainId": 1,
    "blockNumber": "26443964n",
    "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86",
    "timestamp": "1795029143n"
  },
  "snapshots": {
    "1": {
      "chainId": 1,
      "blockNumber": "26443964n",
      "blockHash": "0xe75c58ea2f28bd7c6cc53c28a5ab4fc02023f3563661f0a7236a36b779e3ac86",
      "timestamp": "1795029143n"
    }
  },
  "asOfToken": null,
  "completeness": "full",
  "unsupportedReason": null,
  "unsupportedFields": [],
  "origin": null,
  "indexer": "bigname",
  "items": [
    {
      "id": "c3632a2b4582290d29bcc6f8c3b3b542664ce1257e2783dd83dcf02554451942",
      "type": "record",
      "action": "record_changed",
      "kind": null,
      "name": "ens.eth",
      "namespace": "ens",
      "subject": null,
      "registrationId": "04316989-63d2-5789-b7a6-c454b62d0294",
      "contract": "0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41",
      "blockNumber": "26405156n",
      "timestamp": "1794562235n",
      "transactionHash": "0xfc3c4b113b1e57565527d606e84511ee168437c9579f1d7e18ce132b86176687",
      "logIndex": 434,
      "data": {
        "action": "record_changed",
        "key": "contenthash",
        "node": "0x4e34d3a81dc3a20f71bbdf2160492ddaa17ee7e5523757d47153379c13cb46df",
        "resolver": {
          "address": "0x4976fb03c32e5b8cfe2b6ccb31c09ba78ebaba41",
          "chainId": 1
        }
      }
    },
    {
      "id": "ba6ade15daa5bccf278f9290bfe87e3e673541adf7667e7afb436261a44b4ded",
      "type": "record",
      "action": "record_changed",
      "kind": null,
      "name": "ens.eth",
      "namespace": "ens",
      "subject": null,
      "registrationId": "04316989-63d2-5789-b7a6-c454b62d0294",
      "contract": "0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41",
      "blockNumber": "26350975n",
      "timestamp": "1793909915n",
      "transactionHash": "0xba75418b56c3b12e2702ad3e4436f799af3d544ddcd1a97d92ad7de7e458c166",
      "logIndex": 419,
      "data": {
        "action": "record_changed",
        "key": "contenthash",
        "node": "0x4e34d3a81dc3a20f71bbdf2160492ddaa17ee7e5523757d47153379c13cb46df",
        "resolver": {
          "address": "0x4976fb03c32e5b8cfe2b6ccb31c09ba78ebaba41",
          "chainId": 1
        }
      }
    },
    {
      "id": "5bcef94bca0d5de81f752ca12517fbf833d03f1ace6bf1aafd20a561601c3534",
      "type": "record",
      "action": "record_changed",
      "kind": null,
      "name": "ens.eth",
      "namespace": "ens",
      "subject": null,
      "registrationId": "04316989-63d2-5789-b7a6-c454b62d0294",
      "contract": "0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41",
      "blockNumber": "26350931n",
      "timestamp": "1793909387n",
      "transactionHash": "0x403b425f4242030a1beec24a67240f0fbca92cab8ff0768e0c055bbcbe467f53",
      "logIndex": 606,
      "data": {
        "action": "record_changed",
        "key": "contenthash",
        "node": "0x4e34d3a81dc3a20f71bbdf2160492ddaa17ee7e5523757d47153379c13cb46df",
        "resolver": {
          "address": "0x4976fb03c32e5b8cfe2b6ccb31c09ba78ebaba41",
          "chainId": 1
        }
      }
    }
  ],
  "cursor": "7b2276657273696f6e223a312c22736f7274223a22636861696e5f706f736974696f6e5f64657363222c2266696c74657273223a7b22686973746f72795f636f6e7472616374223a2232222c226e616d65223a22656e733a307834653334643361383164633361323066373162626466323136303439326464616131376565376535353233373537643437313533333739633133636234366466222c226e616d657370616365223a22656e73222c2273636f7065223a22626f7468227d2c226c6173745f6974656d223a7b22626c6f636b5f68617368223a22307864343233346166643533616636353032356364653662396364323032363136343164656138326661646333393432353833346361346331353733353238356637222c22626c6f636b5f6e756d626572223a223236333530393331222c22636861696e5f6964223a22657468657265756d2d6d61696e6e6574222c226576656e745f6964656e74697479223a22656e735f76315f756e777261707065645f617574686f726974793a31343a657468657265756d2d6d61696e6e65743a3078643432333461666435336166363530323563646536623963643230323631363431646561383266616463333934323538333463613463313537333532383566373a3078343033623432356634323432303330613162656563323461363732343066306662636139326361623866663037363865306330353562626362653436376635333a3630363a5265636f72644368616e6765643a30222c226c6f675f696e646578223a22363036222c227472616e73616374696f6e5f696e646578223a22343038227d2c22736e617073686f74223a6e756c6c7d",
  "hasMore": true,
  "totalCount": 171
}
```

## See also [#see-also]

- [`event.get`](/docs/reference/sdk/event/get) for recent events from the chain
- `paginate` from `@ensforge/sdk/indexer` to walk every page