> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ntropy.com/batches/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ntropy.com/_mcp/server.

# Batches

The Batches API allows you to submit multiple requests in a single one.  It allows you to maximize throughput while 
remaining under [rate limits](/api/rate-limits). For production environments, we strongly recommend 
integrating this API alongside [Webhooks](/webhooks). This setup minimizes resource usage as no polling as to be 
done.

# Submitting a batch

A batch is an API abstraction that accepts a set of items `data` and an `operation` that corresponds to an
HTTP method and a url. Processing a batch is analogous to making a request per item to `operation` using
`item` as the body of the request.

To submit a batch of transactions, you have to set the `operation` to the appropriate endpoint operation and set each 
item as you would for that request:

<EndpointRequestSnippet endpoint="POST /v3/batches" />

When you submit a batch, since it's an asynchronous operation, you get an `id` and some metadata:
<EndpointResponseSnippet endpoint="POST /v3/batches" />

# Viewing the progress of a batch

As said in the previous section, for production systems we recommend [webhooks](/webhooks) to receive notifications on
batch progress and status changes. However, you're always free to *poll* for the batch status by querying the batch API
directly supplying its `id`.

<EndpointRequestSnippet endpoint="GET /v3/batches/{id}" />


# Retrieving the results of a batch

When the batch has finished processing its results are ready to be retrieved:

<EndpointRequestSnippet endpoint="GET /v3/batches/{id}/results" />

<Accordion title='See the full raw output'>
    <EndpointResponseSnippet endpoint="GET /v3/batches/{id}/results" />
</Accordion>

## Error handling
A batch is a collection of requests. This way, even if there are some requests that result in an error, these will remain
local to the resource that they pertain to and not influence the global `status` of the batch:

<CodeBlocks>

**`Handling transactions with errors`**

```python title="Handling transactions with errors"
from ntropy_sdk import SDK

sdk = SDK("cd1H...Wmhl" )
batch = sdk.batches.get("f203613d2-83c8-4130-8809-d14206eeec20")
if batch.is_completed():
    batch_result = sdk.batches.results(batch.id)
    not_ok = [tx for tx in batch_result.results if tx.error is not None]
    # Handle specific transactions
    ...
elif batch.is_error():
    # Handle batch error
    ...
```

**`Handling with polling`**

```python title="Handling with polling"
from ntropy_sdk import SDK, NtropyBatchError

sdk = SDK("cd1H...Wmhl" )
try:
    batch = sdk.batches.wait_for_results("f203613d2-83c8-4130-8809-d14206eeec20")
    batch_result = sdk.batches.results(batch.id)
    not_ok = [tx for tx in batch_result.results if tx.error is not None]
    # Handle specific transactions
except NtropyBatchError as err:
    batch_result = sdk.batches.results(err.batch_id)
    # Handle batch error
    ...
```

</CodeBlocks>

When the batch has an `error` status it means that there was an unexpected error in the processing. These are rare and 
can often be solved by retrying the batch. Results are not available in these cases.

---------------------------------------------------------------------