Create batch

POST /api/v1/batches/

Python

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())

200 OK

{
  "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"
  }
}

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.

Prerequisites: You must first upload an input file using the Files API before creating a batch.

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.

Keywords AI parameters

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

-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

input_file_id · string · required

ID of the uploaded JSONL file containing batch requests. Get this from the upload file endpoint.

Example

"input_file_id": "file-abc123"

endpoint · string · required

The API endpoint to be used for all requests in the batch.

Supported values:

• "/v1/chat/completions" - For chat completion requests

Example

"endpoint": "/v1/chat/completions"

completion_window · string · required

Time frame for batch processing completion.

Supported values:

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

Example

"completion_window": "24h"

metadata · object

Optional custom key-value pairs for tracking and organization.

Example

{
  "metadata": {
    "description": "Customer analysis batch",
    "version": "v2.0"
  }
}

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

200 OK

{
  "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"
  }
}

Python

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())