> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plaisolutions.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Batches

> API endpoints for managing batch processing operations for large-scale AI tasks

## List Batches

<api-endpoint method="GET" path="/batches" />

List all batches in the current project with pagination support.

### Query Parameters

<ParamField query="page" type="integer" optional>
  Number of pages to return (default: 1)
</ParamField>

<ParamField query="page_size" type="integer" optional>
  Number of batches to return (default: 100, max: 100)
</ParamField>

<ParamField query="order" type="string" optional>
  Sort order for results (default: "desc")

  * `asc` - Ascending order (oldest first)
  * `desc` - Descending order (newest first)
</ParamField>

### Response

<ResponseField name="batches" type="array">
  Array of batch objects

  <Expandable title="Batch Object">
    <ResponseField name="id" type="string">
      Batch unique identifier
    </ResponseField>

    <ResponseField name="name" type="string">
      Batch name
    </ResponseField>

    <ResponseField name="description" type="string">
      Batch description
    </ResponseField>

    <ResponseField name="status" type="string">
      Current batch status:

      * `validating` - Input file validation in progress
      * `failed` - Batch processing failed
      * `in_progress` - Batch is being processed
      * `finalizing` - Processing complete, preparing output
      * `completed` - Batch completed successfully
      * `expired` - Batch expired before completion
      * `cancelling` - Cancellation in progress
      * `cancelled` - Batch was cancelled
    </ResponseField>

    <ResponseField name="type" type="string">
      Batch processing type:

      * `COMPLETIONS` - Text completion/generation tasks
      * `EMBEDDINGS` - Vector embedding generation
    </ResponseField>

    <ResponseField name="callback_url" type="string">
      URL to notify when batch completes
    </ResponseField>

    <ResponseField name="delivered_at" type="string">
      When notification was delivered (ISO 8601 format)
    </ResponseField>

    <ResponseField name="input_file_url" type="string">
      URL of the input file for batch processing
    </ResponseField>

    <ResponseField name="has_output_file" type="boolean">
      Whether output file is available for download
    </ResponseField>

    <ResponseField name="has_errors_file" type="boolean">
      Whether errors file is available for download
    </ResponseField>

    <ResponseField name="project_id" type="string">
      ID of the project this batch belongs to
    </ResponseField>

    <ResponseField name="created_at" type="string">
      When the batch was created (ISO 8601 format)
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      When the batch was last updated (ISO 8601 format)
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request GET 'https://api.plaisolutions.com/batches?page=1&order=desc' \
  --header 'Authorization: Bearer YOUR_TOKEN'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.plaisolutions.com/batches?page=20&order=desc', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    }
  });

  const batches = await response.json();
  console.log(batches);
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.plaisolutions.com/batches"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN",
      "Content-Type": "application/json"
  }
  params = {
      "page": 1,
      "order": "desc"
  }

  response = requests.get(url, headers=headers, params=params)
  batches = response.json()
  print(batches)
  ```
</CodeGroup>

***

## Create Batch

<api-endpoint method="POST" path="/batches" />

Create a new batch for processing large volumes of AI tasks asynchronously.

### Request Body

<ParamField body="name" type="string" required>
  Descriptive name for the batch
</ParamField>

<ParamField body="description" type="string" optional>
  Optional description of the batch purpose
</ParamField>

<ParamField body="type" type="string" required>
  Type of batch processing:

  * `COMPLETIONS` - For text completion/generation tasks
  * `EMBEDDINGS` - For vector embedding generation
</ParamField>

<ParamField body="input_file_url" type="string" required>
  URL of the input file containing batch requests (JSONL format)
</ParamField>

<ParamField body="callback_url" type="string" required>
  URL to receive webhook notification when batch completes
</ParamField>

### Response

Returns the created batch object with status "validating".

<CodeGroup>
  ```bash cURL theme={null}
  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"
  }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.plaisolutions.com/batches', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      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"
    })
  });

  const batch = await response.json();
  console.log(batch);
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.plaisolutions.com/batches"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN",
      "Content-Type": "application/json"
  }
  data = {
      "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"
  }

  response = requests.post(url, headers=headers, json=data)
  batch = response.json()
  print(batch)
  ```
</CodeGroup>

***

## Get Batch

<api-endpoint method="GET" path="/batches/{batch_id}" />

Get detailed information about a specific batch, including error details if any processing failures occurred.

### Path Parameters

<ParamField path="batch_id" type="string" required>
  The unique identifier of the batch
</ParamField>

### Response

<ResponseField name="batch" type="object">
  Complete batch object including error details

  <Expandable title="Additional Fields">
    <ResponseField name="errors" type="array">
      Array of error objects (if any processing errors occurred)

      <Expandable title="Error Object">
        <ResponseField name="code" type="string">
          Error code identifying the type of error
        </ResponseField>

        <ResponseField name="line" type="integer">
          Line number in input file where error occurred
        </ResponseField>

        <ResponseField name="message" type="string">
          Human-readable error message
        </ResponseField>

        <ResponseField name="param" type="string">
          Parameter that caused the error
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request GET 'https://api.plaisolutions.com/batches/batch_123' \
  --header 'Authorization: Bearer YOUR_TOKEN'
  ```

  ```javascript JavaScript theme={null}
  const batchId = 'batch_123';
  const response = await fetch(`https://api.plaisolutions.com/batches/${batchId}`, {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    }
  });

  const batch = await response.json();
  console.log(batch);
  ```

  ```python Python theme={null}
  import requests

  batch_id = "batch_123"
  url = f"https://api.plaisolutions.com/batches/{batch_id}"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN",
      "Content-Type": "application/json"
  }

  response = requests.get(url, headers=headers)
  batch = response.json()
  print(batch)
  ```
</CodeGroup>

***

## Download Batch Files

<api-endpoint method="GET" path="/batches/{batch_id}/download" />

Download the output and error files for a completed batch.

### Path Parameters

<ParamField path="batch_id" type="string" required>
  The unique identifier of the completed batch
</ParamField>

### Response

<ResponseField name="output_file_url" type="string">
  Pre-signed URL to download the batch output file (JSONL format)
</ResponseField>

<ResponseField name="errors_file_url" type="string">
  Pre-signed URL to download the batch errors file (if any errors occurred)
</ResponseField>

<Note>
  Download URLs are temporary and expire after a short period. Download the files immediately after receiving the URLs.
</Note>

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request GET 'https://api.plaisolutions.com/batches/batch_123/download' \
  --header 'Authorization: Bearer YOUR_TOKEN'
  ```

  ```javascript JavaScript theme={null}
  const batchId = 'batch_123';
  const response = await fetch(`https://api.plaisolutions.com/batches/${batchId}/download`, {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    }
  });

  const downloadUrls = await response.json();
  console.log('Output file:', downloadUrls.output_file_url);
  console.log('Errors file:', downloadUrls.errors_file_url);

  // Download the files
  const outputResponse = await fetch(downloadUrls.output_file_url);
  const outputData = await outputResponse.text();
  ```

  ```python Python theme={null}
  import requests

  batch_id = "batch_123"
  url = f"https://api.plaisolutions.com/batches/{batch_id}/download"
  headers = {
      "Authorization": "Bearer YOUR_TOKEN",
      "Content-Type": "application/json"
  }

  response = requests.get(url, headers=headers)
  download_urls = response.json()

  print(f"Output file: {download_urls['output_file_url']}")
  print(f"Errors file: {download_urls['errors_file_url']}")

  # Download the output file
  output_response = requests.get(download_urls['output_file_url'])
  output_data = output_response.text
  ```
</CodeGroup>

***

## Check Batch Status

<api-endpoint method="GET" path="/batches/check-batches" />

Administrative endpoint to check and update the status of all batches. This endpoint is typically used by system administrators or automated processes.

<Warning>
  This endpoint requires API key authentication with `Users-Management-Key` header and is intended for administrative use.
</Warning>

### Response

Returns the result of the batch status check operation.

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request GET 'https://api.plaisolutions.com/batches/check-batches' \
  --header 'Users-Management-Key: YOUR_MANAGEMENT_KEY'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.plaisolutions.com/batches/check-batches', {
    method: 'GET',
    headers: {
      'Users-Management-Key': 'YOUR_MANAGEMENT_KEY',
      'Content-Type': 'application/json'
    }
  });

  const result = await response.json();
  console.log(result);
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.plaisolutions.com/batches/check-batches"
  headers = {
      "Users-Management-Key": "YOUR_MANAGEMENT_KEY",
      "Content-Type": "application/json"
  }

  response = requests.get(url, headers=headers)
  result = response.json()
  print(result)
  ```
</CodeGroup>

***

## Input File Format

Batch input files must be in JSONL (JSON Lines) format, with each line containing a valid JSON object representing a single request.

### Completions Batch Format

For text completion tasks, each line should contain:

```json theme={null}
{"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"}}
```

### Embeddings Batch Format

For embedding generation tasks, each line should contain:

```json theme={null}
{"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 File Format

Output files are also in JSONL format, with each line containing the response for the corresponding input request:

```json theme={null}
{"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

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="batch.completed">
    Sent when a batch finishes processing successfully
  </Accordion>

  <Accordion title="batch.failed">
    Sent when a batch fails due to validation or processing errors
  </Accordion>

  <Accordion title="batch.expired">
    Sent when a batch expires before completion
  </Accordion>

  <Accordion title="batch.cancelled">
    Sent when a batch is cancelled manually
  </Accordion>
</AccordionGroup>

***

## Best Practices

<Steps>
  <Step title="File Size Optimization">
    Keep input files under 100MB for optimal processing speed. Split larger datasets into multiple batches.
  </Step>

  <Step title="Custom IDs">
    Use meaningful custom IDs that help you correlate responses with your original requests.
  </Step>

  <Step title="Error Handling">
    Always check for both output and error files. Handle partial failures gracefully.
  </Step>

  <Step title="Webhook Security">
    Implement webhook signature verification to ensure notifications come from PLai.
  </Step>

  <Step title="Rate Limiting">
    Batch processing helps avoid rate limits, but don't submit too many concurrent batches.
  </Step>
</Steps>

### Cost Optimization

<Tip>
  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
</Tip>

### Monitoring and Troubleshooting

<CardGroup cols={2}>
  <Card title="Monitor Progress" icon="chart-line">
    Check batch status regularly and set up proper webhook handling for notifications
  </Card>

  <Card title="Error Recovery" icon="refresh">
    Download error files to identify failed requests and reprocess them if needed
  </Card>

  <Card title="Performance Tuning" icon="gauge">
    Optimize batch size and request complexity based on processing times
  </Card>

  <Card title="Backup Strategy" icon="shield">
    Keep copies of input files and download output files promptly before they expire
  </Card>
</CardGroup>

### Security Considerations

<Warning>
  * 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
</Warning>