# batch

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

Runs several reads together, in as few round trips as possible. Parameters, return value, errors and examples for batch in @ensforge/sdk.

Source: https://ensforge.com/docs/reference/sdk/batch

<ApiMeta kind="Read" stability="stable" since="1.0.0" source="packages/sdk/src/batch/index.ts#L66" />

Runs several reads together, in as few round trips as possible.

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

Use to load a page's data at once: profiles, names, prices, permissions.

## Details [#details]

- `requests` is a list (results come back as a tuple) or a record (results keep its keys).
- Contract reads coalesce into Multicall3 calls, per block; resolution reads (records, primary
  names) keep their Universal Resolver call, so CCIP-Read and off-chain names work.
- With `allowFailure` (default) each result is `{ status: "success", result }` or
  `{ status: "failure", error }`; with `allowFailure: false` the first failure rejects.
- Only reads with `.request` can be batched; writes combine with `Plan.merge`.

## Signature [#signature]

```ts
function batch<const requests extends Requests, allowFailure extends boolean = true>(
  client: Like,
  options: BatchOptions<requests, allowFailure>,
): Promise<batch.ReturnType<requests, allowFailure>>
```

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

## Parameters [#parameters]

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `requests` (required) | `Requests` |  | Deferred reads from `action.request(options)`, as a list or a record. |
| `allowFailure` | `boolean` | `true` | Report each request's failure in its result instead of failing the batch. |
| `signal` | `AbortSignal` |  | Cancels the batch; the Promise rejects with `signal.reason`. |

## Returns [#returns]

Resolves to `{ readonly results: Results<requests, allowFailure>; }`. Results in the requests' shape.

| Field | Type | Description |
| --- | --- | --- |
| `results` | `Results<Requests, boolean>` |  |

## Errors [#errors]

| Error | Codes | When |
| --- | --- | --- |
| [`InvalidInputError`](/docs/reference/errors/invalid-input-error) | [`INVALID_RECORD_VALUE`](/docs/reference/errors/INVALID_RECORD_VALUE) | a request that cannot be batched. |
|  |  | The first request's error with `allowFailure: false`. |

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={["Standalone","Effect"]} persist>
<Tab>
```ts title="Loading a profile"
import { Actions } from "@ensforge/sdk"

const { results } = await ens.batch({
  requests: {
    address: Actions.record.getAddress.request({ name: "nick.eth" }),
    avatar: Actions.record.getText.request({ name: "nick.eth", key: "avatar" }),
  },
})
```

```ts title="A list with a standalone call"
import { Actions } from "@ensforge/sdk"

const { results: [state, primary] } = await Actions.batch(publicClient, {
  requests: [Actions.name.get.request({ name: "nick.eth" }), Actions.primaryName.get.request({ address })],
  allowFailure: false,
})
```
</Tab>

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

const { results } = yield* Actions.batch(ens, {
  requests: [Requests.name.get.request({ name: "nick.eth" })],
})
```
</Tab>
</Tabs>

## See also [#see-also]

- [`name.get`](/docs/reference/sdk/name/get) and every other read's `.request`