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

# Batch API

> Submit requests inline, create a batch, poll for completion, and read results inline.

The Batch API is for asynchronous, high-volume inference jobs where you do not need an answer immediately.

## Workflow

1. Prepare a request bundle
2. Create a batch with `POST /v1/batches`
3. Poll `GET /v1/batches/{batch_id}` — results are included inline once complete

## 1 & 2. Create the batch

Pass your requests inline — no separate file upload required.

<Tabs>
  <Tab title="curl">
    ```bash theme={null}
    curl https://api.meshapi.ai/v1/batches \
      -H "Authorization: Bearer <YOUR_RSK_KEY>" \
      -H "Content-Type: application/json" \
      -d '{
        "requests": [
          {
            "custom_id": "doc-001",
            "body": {
              "model": "openai/gpt-5.4",
              "messages": [{ "role": "user", "content": "Summarize this note." }]
            }
          }
        ],
        "completion_window": "24h"
      }'
    ```
  </Tab>

  <Tab title="Node.js SDK">
    ```ts theme={null}
    const batch = await client.batches.create({
      requests: [
        {
          custom_id: "doc-001",
          body: {
            model: "openai/gpt-5.4",
            messages: [{ role: "user", content: "Summarize this note." }],
          },
        },
      ],
      completion_window: "24h",
    });
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    from meshapi import BatchRequestItem, CreateBatchParams, MeshAPI

    client = MeshAPI(base_url="https://api.meshapi.ai", token="rsk_...")

    batch = client.batches.create(
        CreateBatchParams(
            requests=[
                BatchRequestItem(
                    custom_id="doc-001",
                    body={
                        "model": "openai/gpt-5.4",
                        "messages": [{"role": "user", "content": "Summarize this note."}],
                    },
                )
            ],
            completion_window="24h",
        )
    )
    ```
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    batch, err := client.Batches.Create(ctx, meshapi.CreateBatchParams{
        Requests: []meshapi.BatchRequestItem{
            {
                CustomID: "doc-001",
                Body: map[string]interface{}{
                    "model": "openai/gpt-5.4",
                    "messages": []map[string]string{
                        {"role": "user", "content": "Summarize this note."},
                    },
                },
            },
        },
        CompletionWindow: "24h",
    })
    ```
  </Tab>

  <Tab title="Java SDK">
    ```java theme={null}
    var item = new com.meshapi.sdk.types.batch.BatchRequestItem();
    item.customId = "doc-001";
    item.body = java.util.Map.of(
        "model", "openai/gpt-5.4",
        "messages", java.util.List.of(java.util.Map.of("role", "user", "content", "Summarize this note."))
    );

    var batchRequest = new com.meshapi.sdk.types.batch.CreateBatchRequest();
    batchRequest.requests = java.util.List.of(item);
    batchRequest.completionWindow = "24h";

    var batch = client.batches().create(batchRequest);
    ```
  </Tab>
</Tabs>

### Request item fields

Each entry in `requests` supports:

| Field       | Type   | Notes                                                              |
| ----------- | ------ | ------------------------------------------------------------------ |
| `custom_id` | string | Your identifier, echoed back on the matching result. **Required.** |
| `body`      | object | The request body (e.g. a chat completion payload). **Required.**   |
| `method`    | string | HTTP method. Defaults to `POST`.                                   |
| `url`       | string | Target endpoint. Defaults to `/v1/chat/completions`.               |

The batch create call also accepts an optional `metadata` object (arbitrary key-value pairs) alongside `completion_window`.

### Limits

* A batch may not mix models — all requests must target the same model, or the create call returns `400 mixed_models`.
* You can have at most **10 batches in a non-terminal state** at once; an eleventh returns `429 batch_limit_exceeded`.

## 3. Poll and read results

Poll until `status` is a terminal value. When `completed`, the response includes a `results` array — no separate file download needed.

```bash theme={null}
curl https://api.meshapi.ai/v1/batches/batch_xyz789 \
  -H "Authorization: Bearer <YOUR_RSK_KEY>"
```

```json theme={null}
{
  "id": "batch_xyz789",
  "status": "completed",
  "request_counts": { "total": 1, "completed": 1, "failed": 0 },
  "results": [
    {
      "custom_id": "doc-001",
      "response": {
        "status_code": 200,
        "body": {
          "choices": [{ "message": { "content": "The note says..." } }],
          "usage": { "prompt_tokens": 12, "completion_tokens": 40 }
        }
      },
      "error": null
    }
  ]
}
```

Common statuses:

* `validating`
* `in_progress`
* `finalizing`
* `completed`
* `failed`
* `cancelling`
* `cancelled`
* `expired`

## Notes

* All requests in a batch must use the same model.
* Batch jobs are best for throughput, not low-latency interactive use.
* Use `GET /v1/batches` to list recent batches and `POST /v1/batches/{batch_id}/cancel` to cancel one.
* Results are matched by `custom_id` — the output order is not guaranteed.

***

## Batch statuses

| Status        | Meaning                                                                |
| ------------- | ---------------------------------------------------------------------- |
| `validating`  | Submitted — file is being validated before processing starts           |
| `in_progress` | Processing — keep polling                                              |
| `finalizing`  | Processing complete — output file is being assembled                   |
| `completed`   | All requests finished                                                  |
| `failed`      | Batch-level failure (individual item failures are in `response.error`) |
| `cancelling`  | Cancellation requested — winding down                                  |
| `cancelled`   | Cancelled before completion                                            |
| `expired`     | Batch exceeded the completion window and was not finished              |

## Cancelling a batch

```bash theme={null}
curl -X POST https://api.meshapi.ai/v1/batches/batch_01abc.../cancel \
  -H "Authorization: Bearer rsk_YOUR_KEY"
```

Returns the updated batch object. The status transitions to `cancelling` and eventually `cancelled`. Partial results may still be available.

## Listing batches

```bash theme={null}
curl https://api.meshapi.ai/v1/batches \
  -H "Authorization: Bearer rsk_YOUR_KEY"
```

Supports cursor-based pagination via `after` (batch ID) and `limit` (1–100, default 20) query parameters.

## When to use batching

* **Large-scale data processing** — summarizing, classifying, or translating thousands of documents
* **Overnight jobs** — non-urgent workloads that can run during off-peak hours
* **Cost efficiency** — batch jobs can be prioritized for cheaper execution windows