> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kyberis.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch Responses

> Interpret per-item results from Kyberis batch endpoints.

Batch endpoints return item-level outcomes. Agents should preserve the status of every item.

## Response Envelope

Batch endpoints return an envelope with per-item results and batch metadata:

| Field      | Meaning                                                                         |
| ---------- | ------------------------------------------------------------------------------- |
| `items`    | Per-item results in request order.                                              |
| `metadata` | Batch-level counts, timing, truncation, and implementation notes when provided. |

Each `items` entry has:

| Field    | Meaning                                                     |
| -------- | ----------------------------------------------------------- |
| `index`  | Zero-based position of the original request item.           |
| `status` | Item outcome, independent of the HTTP status for the batch. |
| `result` | Endpoint-specific response payload for successful items.    |
| `error`  | Item-level error details for failed items.                  |

Each item should be interpreted independently. A successful HTTP response can still contain item-level failures.

## Agent Behavior

* Report successes, ambiguous items, validation failures, and access failures separately.
* Preserve item indexes or input IDs so callers can map outputs back to inputs.
* Retry only the items that failed for transient reasons.
* Split oversized batches when you hit `batch_limit_exceeded` or plan-specific limits.

## Do not Hide Partial Failure

A batch response can be useful even when some items fail. Summarize the successful items and clearly list items that need correction, new scopes, or smaller batches.