# indexer.getNamesByExpiry

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

Lists names by when they expire or leave their grace period. Parameters, return value, errors and examples for indexer.getNamesByExpiry in @ensforge/sdk.

Source: https://ensforge.com/docs/reference/sdk/indexer/get-names-by-expiry

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

Lists names by when they expire or leave their grace period.

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

Use to find names expiring soon, e.g. renewal reminders or a drop-catching list.

## Details [#details]

- Pass either expiry bounds (`expiresAfter`, `expiresBefore`, `windows`) or grace bounds
  (`graceEndsAfter`, `graceEndsBefore`, `graceWindows`), not both.
- With `windows`, each name reports the window it matched (`windowIndex`).

## Signature [#signature]

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

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

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

## 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. |
| `expiresAfter` | `bigint \| Date` |  |  |
| `expiresBefore` | `bigint \| Date` |  |  |
| `windows` | `readonly Window[]` |  | Up to 32 disjoint expiry windows; results report the matching `windowIndex`. |
| `graceEndsAfter` | `bigint \| Date` |  |  |
| `graceEndsBefore` | `bigint \| Date` |  |  |
| `graceWindows` | `readonly Window[]` |  |  |
| `authority` | `Authority \| readonly Authority[]` |  |  |
| `parent` | `string` |  |  |
| `sort` | `"expiry" \| "graceEnd"` |  | Field the rows are sorted by. |
| `order` | `"asc" \| "desc"` |  | Sort direction. |
| `namespace` | `Namespace` | `"ens"` |  |

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

## Returns [#returns]

Resolves to `Page<ExpiringName>`. One page of names, soonest first unless `order` says otherwise.

## Errors [#errors]

| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_NAME`](/docs/reference/errors/INVALID_NAME) | `parent` does not normalize. |
| [`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 names expiring this month"
const page = await ens.indexer.getNamesByExpiry({ expiresAfter: new Date(), expiresBefore: inAMonth })
```
</Tab>

<Tab>
```ts title="Listing names leaving grace with a standalone call"
import { Actions } from "@ensforge/sdk"

const page = await Actions.indexer.getNamesByExpiry(ens, { graceEndsBefore: tomorrow })
```
</Tab>

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

const page = yield* Actions.indexer.getNamesByExpiry(ens, { parent: "eth", expiresBefore: inAWeek })
```
</Tab>
</Tabs>