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

# Batches

> Submit async batch jobs, check status, and cancel pending batches.

The Batch API lets you submit many requests at once and retrieve results asynchronously — useful for large-scale processing where latency is not critical.

<Info>
  Not all models support the Batch API. `openai/gpt-5-nano` is confirmed to support batching.
</Info>

## Create a batch

Pass an array of `requests`, each with a `custom_id` for correlating results and a `body` containing the chat completion parameters.

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

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

    batch = client.batches.create(
        CreateBatchParams(
            requests=[
                BatchRequestItem(
                    custom_id="req-1",
                    body={
                        "model": "openai/gpt-5-nano",
                        "messages": [{"role": "user", "content": "Reply with the single word: hello"}],
                        "max_tokens": 16,
                    },
                ),
                BatchRequestItem(
                    custom_id="req-2",
                    body={
                        "model": "openai/gpt-5-nano",
                        "messages": [{"role": "user", "content": "Reply with the single word: world"}],
                        "max_tokens": 16,
                    },
                ),
            ],
            metadata={"suite": "my-batch-job"},
        )
    )
    print(batch.id)
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const batch = await client.batches.create({
      requests: [
        {
          custom_id: "req-1",
          body: {
            model: "openai/gpt-5-nano",
            messages: [{ role: "user", content: "Reply with the single word: hello" }],
            max_tokens: 10,
          },
        },
        {
          custom_id: "req-2",
          body: {
            model: "openai/gpt-5-nano",
            messages: [{ role: "user", content: "Reply with the single word: world" }],
            max_tokens: 10,
          },
        },
      ],
      metadata: { suite: "my-batch-job" },
    });
    console.log(batch.id);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    batch, err := client.Batches.Create(ctx, meshapi.CreateBatchParams{
        Requests: []meshapi.BatchRequestItem{
            {
                CustomID: "req-1",
                Body: map[string]interface{}{
                    "model":      "openai/gpt-5-nano",
                    "messages":   []map[string]interface{}{{"role": "user", "content": "Reply with the single word: hello"}},
                    "max_tokens": 10,
                },
            },
            {
                CustomID: "req-2",
                Body: map[string]interface{}{
                    "model":      "openai/gpt-5-nano",
                    "messages":   []map[string]interface{}{{"role": "user", "content": "Reply with the single word: world"}},
                    "max_tokens": 10,
                },
            },
        },
        Metadata: map[string]interface{}{"suite": "go-batch-job"},
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(batch.ID)
    ```
  </Tab>
</Tabs>

## List batches

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    batch_list = client.batches.list(limit=10)
    for item in batch_list.data:
        print(item.id, item.status)
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const list = await client.batches.list({ limit: 10 });
    list.data.forEach(b => console.log(b.id, b.status));
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    limit := 10
    listed, err := client.Batches.List(ctx, nil, &limit)
    for _, item := range listed.Data {
        fmt.Println(item.ID, item.Status)
    }
    ```
  </Tab>
</Tabs>

## Get a batch

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    got = client.batches.get(batch.id)
    print(got.id, got.status)
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const got = await client.batches.get(batch.id);
    console.log(got.id, got.status);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    got, err := client.Batches.Get(ctx, batch.ID)
    fmt.Println(got.ID, got.Status)
    ```
  </Tab>
</Tabs>

## Cancel a batch

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    cancelled = client.batches.cancel(batch.id)
    print(cancelled.id)
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const cancelled = await client.batches.cancel(batch.id);
    console.log(cancelled.id);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    cancelled, err := client.Batches.Cancel(ctx, batch.ID)
    fmt.Println(cancelled.ID, cancelled.Status)
    ```
  </Tab>
</Tabs>