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

# Batches.

> For offline and high-volume work: submit many requests in one call, poll until the batch ends, fetch results as JSONL. Two flavors of the same machinery — pick the one whose request shape your items use.

## Two flavors, one lifecycle

| Collection             | Item params                                             | Auth header             |
| ---------------------- | ------------------------------------------------------- | ----------------------- |
| `/v1/messages/batches` | Anthropic [Messages](/api/messages) bodies              | `x-api-key`             |
| `/v1/batches`          | OpenAI [Chat Completions](/api/chat-completions) bodies | `Authorization: Bearer` |

Both collections expose the same five operations. Everything below is written against
`/v1/messages/batches`; substitute the path and item shape for the OpenAI flavor.

## Create a batch

```http theme={null}
POST /v1/messages/batches
```

Send an inline `requests` array. Each item carries a `custom_id` (yours, for matching
results) and a `params` object — the same body you would send to the live endpoint.

```sh title="Create" theme={null}
curl https://api.layerx1.com/v1/messages/batches \
  -H "x-api-key: $LAYERX1_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "requests": [
      {
        "custom_id": "req-1",
        "params": {
          "model": "lx1-gpt-oss-120b",
          "max_tokens": 256,
          "messages": [{ "role": "user", "content": "First task" }]
        }
      },
      {
        "custom_id": "req-2",
        "params": {
          "model": "lx1-gpt-oss-120b",
          "max_tokens": 256,
          "messages": [{ "role": "user", "content": "Second task" }]
        }
      }
    ]
  }'
```

| Limit              | Value  |
| ------------------ | ------ |
| Requests per batch | 1,000  |
| Size per item      | 100 KB |

## Lifecycle

```http theme={null}
GET  /v1/messages/batches
GET  /v1/messages/batches/{id}
POST /v1/messages/batches/{id}/cancel
GET  /v1/messages/batches/{id}/results
```

Processing is asynchronous. `processing_status` flows `in_progress → ended` (via
`canceling` if you cancel). Poll the status endpoint; fetch `/results` only once the batch
has `ended` — before that it returns `409`.

### Results

Results are JSONL — one line per request, keyed by your `custom_id`, with a discriminated
`result.type` of `succeeded | errored | canceled | expired`. Order is not guaranteed to
match submission order; always match on `custom_id`.

```json title="Results (JSONL, one line per request)" theme={null}
{"custom_id":"req-1","result":{"type":"succeeded","message":{"id":"msg_...","content":[{"type":"text","text":"..."}]}}}
{"custom_id":"req-2","result":{"type":"errored","error":{"type":"invalid_request_error","message":"..."}}}
```

<Note>
  Batch items draw from the same monthly included-usage pool as live requests, at the same
  public list rates — see [Plans & limits](/plans).
</Note>