Retrieve batch

Retrieve the status and details of a specific batch job. Use this to monitor batch progress and get the output file ID when the batch completes. <Note> **Customer credentials required**: This endpoint requires your own OpenAI API key configured in Respan dashboard (Settings → Providers). </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\"}" ``` ## Path parameters - `batch_id` *string* **required**: The unique identifier of the batch to retrieve. Format: `batch_xxxxx` **Example** ``` batch_abc123 ``` ## Response Returns a batch object with complete status information. **Key fields:** - `status` - Current batch status (see [create batch](/api-reference/develop/open-ai-batch/batches/create) for status values) - `output_file_id` - ID of the output file when batch completes (use with [retrieve file content](/api-reference/develop/open-ai-batch/files/content)) - `error_file_id` - ID of the error file if any requests failed - `request_counts` - Progress tracking with total, completed, and failed counts ```json 200 OK { "id": "batch_abc123", "object": "batch", "endpoint": "/v1/chat/completions", "errors": null, "input_file_id": "file-abc123", "completion_window": "24h", "status": "completed", "output_file_id": "file-xyz789", "error_file_id": null, "created_at": 1711471533, "in_progress_at": 1711471538, "expires_at": 1711557933, "finalizing_at": 1711493133, "completed_at": 1711493163, "failed_at": null, "expired_at": null, "cancelling_at": null, "cancelled_at": null, "request_counts": { "total": 100, "completed": 95, "failed": 5 }, "metadata": { "description": "Customer analysis batch" } } ``` ```json 404 Not Found { "error": { "message": "No such batch: batch_abc123", "type": "invalid_request_error" } } ``` ```json 401 Unauthorized { "error": "Authentication credentials were not provided." } ``` ```python Python batch_id = "batch_abc123" url = f"https://api.respan.ai/api/v1/batches/{batch_id}/" headers = { "Authorization": "Bearer YOUR_API_KEY", "X-Data-Respan-Params": json.dumps({ "customer_identifier": "user123" }) } response = requests.get(url, headers=headers) batch = response.json() print(f"Status: {batch['status']}") if batch['status'] == 'completed': print(f"Output file: {batch['output_file_id']}") ``` ```typescript TypeScript const batchId = 'batch_abc123'; const url = `https://api.respan.ai/api/v1/batches/${batchId}/`; const headers = { 'Authorization': 'Bearer YOUR_API_KEY', 'X-Data-Respan-Params': JSON.stringify({ customer_identifier: 'user123' }) }; const response = await fetch(url, { method: 'GET', headers: headers }); const data = await response.json(); console.log(`Status: ${data.status}`); ``` ```bash cURL curl https://api.respan.ai/api/v1/batches/batch_abc123/ \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "X-Data-Respan-Params: {\"customer_identifier\": \"user123\"}" ```