> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sideren.io/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.sideren.io/v1/messages/batches \
  -H "x-api-key: $SIDEREN_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: nightly-batch-2026-10-01" \
  -d '{
    "requests": [
      {
        "custom_id": "req-1",
        "params": {
          "model": "@sdn/glm-5.3",
          "max_tokens": 256,
          "messages": [{ "role": "user", "content": "First task" }]
        }
      },
      {
        "custom_id": "req-2",
        "params": {
          "model": "@sdn/glm-5.3",
          "max_tokens": 256,
          "messages": [{ "role": "user", "content": "Second task" }]
        }
      }
    ]
  }'
```

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

Rules the create enforces:

* `custom_id` is `1–64` characters of `A–Z`, `a–z`, `0–9`, `_`, `-`, and unique within the
  batch.
* Item `params` take the same shape as the live endpoint, but must not set `stream`.
* An optional `processing_mode` (or `lane`) field picks the execution lane:
  `standard` (default), `flex`, `native-preferred` or `native-required`. The last requires
  a provider-native batch transport; without one the create returns
  `422 native_batch_unavailable`.
* Batches bill from the same monthly included-usage pool as live requests, at the same
  meter — so PAYG-mode batches are refused up front with `400 payg_batch_not_supported`;
  send synchronous requests on PAYG instead.

Create accepts an [`Idempotency-Key`](/api/idempotency) header: a retry with the same key
and body replays the original response instead of submitting twice.

## 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`.

The batch view carries `request_counts` — `processing`, `succeeded`, `errored`, `canceled`,
`expired` — so a poll shows progress, not just state. A cancel keeps the results of items
that already ran; the un-started tail comes back `canceled`.

Batches and their results are kept for **24 hours** from creation; after that, results
return `410` and the storage is reclaimed.

### 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":"error","error":{"type":"invalid_request_error","message":"..."}}}}
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.