---
title: "Return a result for each item in a batch · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/resources-and-methods/batch-results
id: API-91
level: Recommended
updated: 2026-10-22
build: a2a6bdfed830
tokens: 896
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Return a result for each item in a batch

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Resources and methods](https://agentwranglers.se/playbook/api-design/resources-and-methods.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-22.

- ID: API-91
- Level: Recommended
- Chapter: [Resources and methods](https://agentwranglers.se/playbook/api-design/resources-and-methods.md)
- Rule: Give each batch endpoint a written item limit, and say whether it is all or nothing. Return one result per item, in request order, with its own status and error.
- Check: Send a batch of three items where the second is invalid. An all-or-nothing endpoint creates none and names index 1. A partial endpoint creates two and marks index 1 with 422. A batch one item over the limit gets 422 and creates nothing.
- How: A batch saves round trips when a client creates or changes many records. Refuse a batch over the limit with 422 that names the limit, before doing any work. Google's AIP-233 makes a synchronous batch atomic and lets an asynchronous one report failures per item. An all-or-nothing batch runs in one transaction and fails whole, naming the first bad item. A batch that allows partial success answers 200 with a `results` list. Each entry holds the item's index, a status code and either the resource or [problem details](https://agentwranglers.se/playbook/api-design/errors/problem-details.md). Never answer a bare 200 when some items failed. Accept an [idempotency key](https://agentwranglers.se/playbook/api-design/reliability/idempotency-keys.md) for the whole batch, so a retry creates nothing twice. A batch that takes longer than one request runs as a [long job](https://agentwranglers.se/playbook/api-design/reliability/long-running-jobs.md).

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JSON example

```json
{
  "results": [
    { "index": 0, "status": 201, "product": { "id": "prd_81", "sku": "MUG-RED" } },
    { "index": 1, "status": 422, "error": { "type": "https://example.com/problems/invalid-field", "title": "Price must be positive", "field": "price" } },
    { "index": 2, "status": 201, "product": { "id": "prd_82", "sku": "MUG-BLUE" } }
  ]
}
```

## Sources

- [AIP-233 Batch methods: Create](https://google.aip.dev/233)

## Related rules

- API-16 [Send errors as problem details](https://agentwranglers.se/playbook/api-design/errors/problem-details.md) in API design
- API-32 [Accept idempotency keys on POST that creates or charges](https://agentwranglers.se/playbook/api-design/reliability/idempotency-keys.md) in API design
- API-37 [Run long jobs asynchronously](https://agentwranglers.se/playbook/api-design/reliability/long-running-jobs.md) in API design

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/api-design/resources-and-methods/batch-results">Agent Wranglers API design playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Keep addresses stable](https://agentwranglers.se/playbook/api-design/resources-and-methods/stable-addresses.md)
- [Resources and methods](https://agentwranglers.se/playbook/api-design/resources-and-methods.md)