List Batches List all batches in the current project with pagination support.
Query Parameters Number of pages to return (default: 1)
Number of batches to return (default: 100, max: 100)
Sort order for results (default: “desc”)
asc - Ascending order (oldest first)desc - Descending order (newest first) Response Array of batch objects Current batch status:
validating - Input file validation in progressfailed - Batch processing failedin_progress - Batch is being processedfinalizing - Processing complete, preparing outputcompleted - Batch completed successfullyexpired - Batch expired before completioncancelling - Cancellation in progresscancelled - Batch was cancelled Batch processing type:
COMPLETIONS - Text completion/generation tasksEMBEDDINGS - Vector embedding generation URL to notify when batch completes
When notification was delivered (ISO 8601 format)
URL of the input file for batch processing
Whether output file is available for download
Whether errors file is available for download
ID of the project this batch belongs to
When the batch was created (ISO 8601 format)
When the batch was last updated (ISO 8601 format)
curl --location --request GET 'https://api.plaisolutions.com/batches?page=1&order=desc' \ --header 'Authorization: Bearer YOUR_TOKEN'
Create Batch Create a new batch for processing large volumes of AI tasks asynchronously.
Request Body Descriptive name for the batch
Optional description of the batch purpose
Type of batch processing:
COMPLETIONS - For text completion/generation tasksEMBEDDINGS - For vector embedding generation URL of the input file containing batch requests (JSONL format)
URL to receive webhook notification when batch completes
Response Returns the created batch object with status “validating”.
curl --location --request POST 'https://api.plaisolutions.com/batches' \ --header 'Authorization: Bearer YOUR_TOKEN' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Product Descriptions Batch", "description": "Generate product descriptions for Q4 inventory", "type": "COMPLETIONS", "input_file_url": "https://storage.example.com/batch-input.jsonl", "callback_url": "https://yourapp.com/webhooks/batch-complete" }'
Get Batch Get detailed information about a specific batch, including error details if any processing failures occurred.
Path Parameters The unique identifier of the batch
Response Complete batch object including error details Array of error objects (if any processing errors occurred) Error code identifying the type of error
Line number in input file where error occurred
Human-readable error message
Parameter that caused the error
curl --location --request GET 'https://api.plaisolutions.com/batches/batch_123' \ --header 'Authorization: Bearer YOUR_TOKEN'
Download Batch Files Download the output and error files for a completed batch.
Path Parameters The unique identifier of the completed batch
Response Pre-signed URL to download the batch output file (JSONL format)
Pre-signed URL to download the batch errors file (if any errors occurred)
Download URLs are temporary and expire after a short period. Download the files immediately after receiving the URLs.
curl --location --request GET 'https://api.plaisolutions.com/batches/batch_123/download' \ --header 'Authorization: Bearer YOUR_TOKEN'
Check Batch Status Administrative endpoint to check and update the status of all batches. This endpoint is typically used by system administrators or automated processes.
This endpoint requires API key authentication with Users-Management-Key header and is intended for administrative use.
Response Returns the result of the batch status check operation.
curl --location --request GET 'https://api.plaisolutions.com/batches/check-batches' \ --header 'Users-Management-Key: YOUR_MANAGEMENT_KEY'
Batch input files must be in JSONL (JSON Lines) format, with each line containing a valid JSON object representing a single request.
For text completion tasks, each line should contain:
{ "custom_id" : "request-1" , "method" : "POST" , "url" : "/agents/agent_123/invoke" , "body" : { "input" : "Write a product description for wireless headphones" }} { "custom_id" : "request-2" , "method" : "POST" , "url" : "/agents/agent_123/invoke" , "body" : { "input" : "Write a product description for running shoes" }} { "custom_id" : "request-3" , "method" : "POST" , "url" : "/agents/agent_123/invoke" , "body" : { "input" : "Write a product description for coffee maker" }}
For embedding generation tasks, each line should contain:
{ "custom_id" : "embed-1" , "method" : "POST" , "url" : "/vectors" , "body" : { "vectors" : [{ "id" : "doc-1" , "values" : [], "metadata" : { "text" : "First document to embed" }}]}} { "custom_id" : "embed-2" , "method" : "POST" , "url" : "/vectors" , "body" : { "vectors" : [{ "id" : "doc-2" , "values" : [], "metadata" : { "text" : "Second document to embed" }}]}}
Output files are also in JSONL format, with each line containing the response for the corresponding input request:
{ "id" : "batch_123_request-1" , "custom_id" : "request-1" , "response" : { "status_code" : 200 , "body" : { "success" : true , "data" : "Wireless headphones with premium sound quality..." }}} { "id" : "batch_123_request-2" , "custom_id" : "request-2" , "response" : { "status_code" : 200 , "body" : { "success" : true , "data" : "Running shoes designed for comfort and performance..." }}} { "id" : "batch_123_request-3" , "custom_id" : "request-3" , "response" : { "status_code" : 200 , "body" : { "success" : true , "data" : "Coffee maker with advanced brewing technology..." }}}
Webhook Notifications When your batch completes, PLai will send a webhook notification to the callback_url you specified:
Webhook Payload { "event" : "batch.completed" , "batch_id" : "batch_123" , "status" : "completed" , "completed_at" : "2024-01-15T10:30:00Z" , "has_output_file" : true , "has_errors_file" : false }
Webhook Events
Sent when a batch finishes processing successfully
Sent when a batch fails due to validation or processing errors
Sent when a batch expires before completion
Sent when a batch is cancelled manually
Best Practices
File Size Optimization
Keep input files under 100MB for optimal processing speed. Split larger datasets into multiple batches.
Custom IDs
Use meaningful custom IDs that help you correlate responses with your original requests.
Error Handling
Always check for both output and error files. Handle partial failures gracefully.
Webhook Security
Implement webhook signature verification to ensure notifications come from PLai.
Rate Limiting
Batch processing helps avoid rate limits, but don’t submit too many concurrent batches.
Cost Optimization Batch processing typically offers cost savings compared to real-time API calls:
50% cost reduction for completion tasks
30% cost reduction for embedding tasks
No real-time processing overhead
Bulk pricing advantages
Monitoring and Troubleshooting
Monitor Progress Check batch status regularly and set up proper webhook handling for notifications
Error Recovery Download error files to identify failed requests and reprocess them if needed
Performance Tuning Optimize batch size and request complexity based on processing times
Backup Strategy Keep copies of input files and download output files promptly before they expire
Security Considerations
Store input and output files securely with appropriate access controls
Use HTTPS for all callback URLs to ensure secure webhook delivery
Implement proper authentication and authorization for webhook endpoints
Consider data retention policies for batch files
