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-reference/develop/open-ai-batch/files/upload) before creating a batch. </Note> <Note> **Customer credentials required**: This endpoint requires your own OpenAI API key configured in Respan dashboard (Settings → Providers). Respan credits cannot be used for batch processing. </Note> ## Respan parameters You can pass Respan tracking parameters via the `X-Data-Respan-Params` header: ```bash -H "X-Data-Respan-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](/api-reference/develop/open-ai-batch/files/upload) endpoint. **Example** ```json "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** ```json "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** ```json "completion_window": "24h" ``` - `metadata` *object*: Optional custom key-value pairs for tracking and organization. **Example** ```json { "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 ```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" } } ``` ```json 400 Bad Request { "error": { "message": "Invalid input_file_id", "type": "invalid_request_error", "param": "input_file_id", "code": null } } ``` ```json 402 Payment Required { "error": "Please add your OpenAI API key to use the Batch API" } ``` ```json 401 Unauthorized { "error": "Authentication credentials were not provided." } ``` ```python Python url = "https://api.respan.ai/api/v1/batches/" headers = { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", "X-Data-Respan-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 const url = 'https://api.respan.ai/api/v1/batches/'; const headers = { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json', 'X-Data-Respan-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 curl https://api.respan.ai/api/v1/batches/ \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Data-Respan-Params: {\"customer_identifier\": \"user123\", \"environment\": \"production\"}" \ -d '{ "input_file_id": "file-abc123", "endpoint": "/v1/chat/completions", "completion_window": "24h" }' ```