# indexer.getSubnames

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

Lists the direct subnames of a name. Parameters, return value, errors and examples for indexer.getSubnames in @ensforge/sdk.

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

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

Lists the direct subnames of a name.

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

Use to show a name's children, e.g. a subname table with search and sorting.

## Details [#details]

- Includes expired and released children unless `includeExpired: false`.
- `search` matches labels by prefix, or anywhere with `match: "contains"`.
- Fails with `NotFoundError` ([`INDEXER_NOT_FOUND`](/docs/reference/errors/INDEXER_NOT_FOUND)) when the indexer has no such parent.

## Signature [#signature]

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

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

`indexer.getSubnames.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 [`useSubnames`](/docs/reference/react/use-subnames).

## Parameters [#parameters]

| 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. |
| `name` (required) | `string` |  |  |
| `search` | `string` |  |  |
| `match` | `"prefix" \| "contains"` |  | Whether `search` matches from the start of a label (`prefix`) or anywhere (`contains`). |
| `sort` | `"name" \| "expiry" \| "registered"` | `"name"` | Field the rows are sorted by. |
| `order` | `"asc" \| "desc"` |  | Sort direction. |
| `includeExpired` | `boolean` | `true` |  |
| `namespace` | `Namespace` | "basenames" for `*.base.eth`, otherwise "ens" | Namespace of the name. |

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

## Returns [#returns]

Resolves to `Page<Subname>`. One page of subnames.

## Errors [#errors]

| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | the name does not normalize. |
| [`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="Listing subnames"
const page = await ens.indexer.getSubnames({ name: "ens.eth" })
```
</Tab>

<Tab>
```ts title="Searching subnames with a standalone call"
import { Actions } from "@ensforge/sdk"

const page = await Actions.indexer.getSubnames(ens, { name: "ens.eth", search: "dao" })
```
</Tab>

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

const page = yield* Actions.indexer.getSubnames(ens, { name: "ens.eth", sort: "expiry" })
```
</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.getSubnames({ 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": [
    {
      "name": "app.ens.eth",
      "displayName": "app.ens.eth",
      "namespace": "ens",
      "node": "0x50a74dcf107973068dfc00db69ecf98b49d52f5361cb4db5feb740fc9f4f74d1",
      "status": "active",
      "authority": "ensV1",
      "owner": "0xb6E040C9ECAaE172a89bD561c5F73e1C48d28cd9",
      "manager": "0xb6E040C9ECAaE172a89bD561c5F73e1C48d28cd9",
      "registeredAt": null,
      "createdAt": "1611624962n",
      "expiresAt": null,
      "graceEndsAt": null,
      "expiryReason": null,
      "ensV1": {
        "resolver": {
          "chainId": 1,
          "address": "0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41"
        },
        "expiresAt": null,
        "wrapperState": "unwrapped",
        "wrapperExpiresAt": null,
        "wrapperFuses": null
      },
      "labelhash": "0xd6f028ca0e8edb4a8c9757ca4fdccab25fa1e0317da1188108f7d2dee14902fb",
      "subnameCount": null,
      "subregistry": null
    },
    {
      "name": "attestations.ens.eth",
      "displayName": "attestations.ens.eth",
      "namespace": "ens",
      "node": "0x9e5c7a2f2ab8b565c6d2c4851a73decb53d1f6a23c97a2b5b66f21d8ace1bbd5",
      "status": "active",
      "authority": "ensV1",
      "owner": "0xb6E040C9ECAaE172a89bD561c5F73e1C48d28cd9",
      "manager": "0xb6E040C9ECAaE172a89bD561c5F73e1C48d28cd9",
      "registeredAt": null,
      "createdAt": "1744877879n",
      "expiresAt": null,
      "graceEndsAt": null,
      "expiryReason": null,
      "ensV1": {
        "resolver": {
          "chainId": 1,
          "address": "0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63"
        },
        "expiresAt": null,
        "wrapperState": "unwrapped",
        "wrapperExpiresAt": null,
        "wrapperFuses": null
      },
      "labelhash": "0x14a804be56ac3478cdc58c820cb1271d39e4a2511f4c5aec7d2c25d624f24918",
      "subnameCount": null,
      "subregistry": null
    },
    {
      "name": "coldwallet.ens.eth",
      "displayName": "coldwallet.ens.eth",
      "namespace": "ens",
      "node": "0xc867d2bd24b8a88c7d5d416dfab28fec6858b5a86f3a1c94faeab450c34023f6",
      "status": "active",
      "authority": "ensV1",
      "owner": "0x690F0581eCecCf8389c223170778cD9D029606F2",
      "manager": "0x690F0581eCecCf8389c223170778cD9D029606F2",
      "registeredAt": null,
      "createdAt": "1614125684n",
      "expiresAt": null,
      "graceEndsAt": null,
      "expiryReason": null,
      "ensV1": {
        "resolver": {
          "chainId": 1,
          "address": "0x4976fb03C32e5B8cfe2b6cCB31c09Ba78EBaBa41"
        },
        "expiresAt": null,
        "wrapperState": "unwrapped",
        "wrapperExpiresAt": null,
        "wrapperFuses": null
      },
      "labelhash": "0x7d044acfeccf1426368be42c96e62a4cf73d3ea32c44c023cffe9c50ca329c62",
      "subnameCount": null,
      "subregistry": null
    }
  ],
  "cursor": "7b2276657273696f6e223a312c22736f7274223a226e616d65222c2266696c74657273223a7b22696e636c7564655f65787069726564223a2274727565222c226e616d657370616365223a22656e73222c226f72646572223a22617363222c22706172656e74223a22656e733a307834653334643361383164633361323066373162626466323136303439326464616131376565376535353233373537643437313533333739633133636234366466222c2271223a22227d2c226c6173745f6974656d223a7b226368696c645f6c6f676963616c5f6e616d655f6964223a22656e733a307863383637643262643234623861383863376435643431366466616232386665633638353862356138366633613163393466616561623435306333343032336636222c22646973706c61795f6e616d65223a22636f6c6477616c6c65742e656e732e657468222c22736f72745f6b696e64223a226e616d65222c22736f72745f76616c7565223a22227d2c22736e617073686f74223a6e756c6c7d",
  "hasMore": true,
  "totalCount": 23
}
```

## See also [#see-also]

- `paginate` from `@ensforge/sdk/indexer` to walk every page