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

# Batches

> Call /batches with the PHP SDK.

**Methods**: `createBatch()`, `retrieveBatch()`, `cancelBatch()`, `getAsyncJobWebSocketUrl()`, `getBatchWebSocketUrl()`, `asyncJobs()->websocketUrl()`

### Example

```php theme={null}
<?php

require 'vendor/autoload.php';

use AIStats\Sdk\AIStats;

$apiKey = getenv('AI_STATS_API_KEY');
$client = new AIStats(apiKey: $apiKey);

$batch = $client->createBatch([
    'endpoint' => 'responses',
    'input_file_id' => 'file_123',
    'completion_window' => '24h',
    'session_id' => 'agent-run-42',
]);

$status = $client->retrieveBatch($batch['id']);
$cancelling = $client->cancelBatch($batch['id']);
$websocketUrl = $client->getBatchWebSocketUrl($batch['id'], 1500);
```

### Key parameters

* `endpoint` (required): Target endpoint for batch items (e.g., `responses`).
* `input_file_id` (required): File id uploaded via `/files`.
* `completion_window`: e.g., `24h`.
* `session_id`: Optional AI Stats grouping id for logs, sessions, and investigate tooling.
* `webhook`: Optional webhook configuration for async lifecycle notifications.
* `metadata`: Optional object stored with the batch.

### Returns

BatchResponse

Batch responses also surface gateway observability fields such as `request_id`, `provider`, echoed `session_id` / `webhook`, and terminal `billing` / `pricing_lines` when available.

Use `$client->getBatchWebSocketUrl(...)` when you want to subscribe to the documented `/v1/async/batch/{id}/ws` lifecycle stream instead of polling only.
Use `$client->asyncJobs()->websocketUrl("batch", $batchId, ...)` when you want the generic async-jobs resource helper.
Use `$client->getAsyncJobWebSocketUrl("batch", $batchId, ...)` when you want the same generic helper without going through the resource object.