indexer.getHistory
Reads the full history of a name, or of every name an address is related to. Options, result, errors and examples for indexer.getHistory.
Reads the full history of a name, or of every name an address is related to.
When to use
Use to show an activity feed for a name or an account, back to its first event.
Details
- Events use the same
typeandactionvocabulary asevent.get, which reads recent events straight from the chain. - Newest first by default (
order: "asc"for oldest first); each event carries its details (data) unlessincludeData: false. scopeselects the name's own events, its registrations' events, or both (default).
Signature
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.
In React, use useNameHistory.
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.
Returns
Resolves to Page<IndexedEvent>. One page of events.
Errors
| Error | Codes | When |
|---|---|---|
InvalidInputError | INVALID_NAME, INVALID_ADDRESS | invalid input. |
NotFoundError | INDEXER_NOT_FOUND | the indexer has no such name. |
ConfigError | INDEXER_NOT_CONFIGURED | the client has no indexer. |
IndexerError | INDEXER_UNSUPPORTED | the indexer does not serve the query or its namespace. |
IndexerError | INDEXER_UNAVAILABLE, INDEXER_RATE_LIMITED, INDEXER_BEHIND, INDEXER_REQUEST_REJECTED, 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.
Examples
const page = await ens.indexer.getHistory({ name: "nick.eth" })Example response
Recorded from Ethereum mainnet on 2026-11-18 at block 26443964. Values change as the chain does.
await ens.indexer.getHistory({ name: "ens.eth", namespace: "ens", limit: 3 }){
"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
event.getfor recent events from the chainpaginatefrom@ensforge/sdk/indexerto walk every page
Was this page helpful?