Skip to main content
POST
https://api.keywordsai.co
/
api
/
v1
/
batches
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())

{
  "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.
"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
"endpoint": "/v1/chat/completions"
​
completion_window
string
required
Time frame for batch processing completion.Supported values:
  • "24h" - 24-hour completion window (only supported value)
"completion_window": "24h"
​
metadata
object
Optional custom key-value pairs for tracking and organization.
{
  "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
{
  "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"
  }
}

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