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

# Create batch

Create a new batch job for asynchronous processing of multiple LLM requests. Batch processing offers 50% cost savings compared to synchronous API calls, with results delivered within 24 hours.

<Note>
  **Prerequisites**: You must first upload an input file using the [Files API](/api-endpoints/develop/openai-batch/files/upload) before creating a batch.
</Note>

<Note>
  **Customer credentials required**: This endpoint requires your own OpenAI API key configured in Keywords AI dashboard (Settings → Providers). Keywords AI credits cannot be used for batch processing.
</Note>

## Keywords AI parameters

You can pass Keywords AI tracking parameters via the `X-Data-Keywordsai-Params` header:

```bash theme={"system"}
-H "X-Data-Keywordsai-Params: {\"customer_identifier\": \"user123\", \"environment\": \"production\"}"
```

**Supported parameters:**

* `customer_identifier` - User/customer identifier for tracking
* `environment` - Environment label (e.g., "production", "staging")
* `custom_identifier` - Custom identifier for your use case
* `thread_identifier` - Thread/conversation identifier
* `metadata` - Additional key-value metadata

## Request body

<ParamField body="input_file_id" type="string" required>
  ID of the uploaded JSONL file containing batch requests. Get this from the [upload file](/api-endpoints/develop/openai-batch/files/upload) endpoint.

  <Accordion title="Example">
    ```json theme={"system"}
    "input_file_id": "file-abc123"
    ```
  </Accordion>
</ParamField>

<ParamField body="endpoint" type="string" required>
  The API endpoint to be used for all requests in the batch.

  **Supported values:**

  * `"/v1/chat/completions"` - For chat completion requests

  <Accordion title="Example">
    ```json theme={"system"}
    "endpoint": "/v1/chat/completions"
    ```
  </Accordion>
</ParamField>

<ParamField body="completion_window" type="string" required>
  Time frame for batch processing completion.

  **Supported values:**

  * `"24h"` - 24-hour completion window (only supported value)

  <Accordion title="Example">
    ```json theme={"system"}
    "completion_window": "24h"
    ```
  </Accordion>
</ParamField>

<ParamField body="metadata" type="object">
  Optional custom key-value pairs for tracking and organization.

  <Accordion title="Example">
    ```json theme={"system"}
    {
      "metadata": {
        "description": "Customer analysis batch",
        "version": "v2.0"
      }
    }
    ```
  </Accordion>
</ParamField>

## Response

Returns a batch object with status information. The batch starts in `validating` status and progresses through various states until completion.

**Status values:**

* `validating` - Input file is being validated
* `failed` - Validation failed
* `in_progress` - Batch is processing
* `finalizing` - Batch processing complete, output file being created
* `completed` - Batch successfully completed
* `expired` - Batch expired before completion
* `cancelling` - Cancellation in progress
* `cancelled` - Batch was cancelled

<ResponseExample>
  ```json 200 OK theme={"system"}
  {
    "id": "batch_abc123",
    "object": "batch",
    "endpoint": "/v1/chat/completions",
    "errors": null,
    "input_file_id": "file-abc123",
    "completion_window": "24h",
    "status": "validating",
    "output_file_id": null,
    "error_file_id": null,
    "created_at": 1711471533,
    "in_progress_at": null,
    "expires_at": 1711557933,
    "finalizing_at": null,
    "completed_at": null,
    "failed_at": null,
    "expired_at": null,
    "cancelling_at": null,
    "cancelled_at": null,
    "request_counts": {
      "total": 100,
      "completed": 0,
      "failed": 0
    },
    "metadata": {
      "description": "Customer analysis batch"
    }
  }
  ```

  ```json 400 Bad Request theme={"system"}
  {
    "error": {
      "message": "Invalid input_file_id",
      "type": "invalid_request_error",
      "param": "input_file_id",
      "code": null
    }
  }
  ```

  ```json 402 Payment Required theme={"system"}
  {
    "error": "Please add your OpenAI API key to use the Batch API"
  }
  ```

  ```json 401 Unauthorized theme={"system"}
  {
    "error": "Authentication credentials were not provided."
  }
  ```
</ResponseExample>

<RequestExample>
  ```python Python theme={"system"}
  import requests
  import json

  url = "https://api.keywordsai.co/api/v1/batches/"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
      "X-Data-Keywordsai-Params": json.dumps({
          "customer_identifier": "user123",
          "environment": "production"
      })
  }
  payload = {
      "input_file_id": "file-abc123",
      "endpoint": "/v1/chat/completions",
      "completion_window": "24h",
      "metadata": {
          "description": "Customer analysis batch"
      }
  }

  response = requests.post(url, headers=headers, json=payload)
  print(response.json())
  ```

  ```typescript TypeScript theme={"system"}
  const url = 'https://api.keywordsai.co/api/v1/batches/';
  const headers = {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
      'X-Data-Keywordsai-Params': JSON.stringify({
          customer_identifier: 'user123',
          environment: 'production'
      })
  };

  const payload = {
      input_file_id: 'file-abc123',
      endpoint: '/v1/chat/completions',
      completion_window: '24h',
      metadata: {
          description: 'Customer analysis batch'
      }
  };

  const response = await fetch(url, {
      method: 'POST',
      headers: headers,
      body: JSON.stringify(payload)
  });

  const data = await response.json();
  console.log(data);
  ```

  ```bash cURL theme={"system"}
  curl https://api.keywordsai.co/api/v1/batches/ \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Data-Keywordsai-Params: {\"customer_identifier\": \"user123\", \"environment\": \"production\"}" \
    -d '{
      "input_file_id": "file-abc123",
      "endpoint": "/v1/chat/completions",
      "completion_window": "24h"
    }'
  ```
</RequestExample>