> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/portkey-AI/gateway/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve Batch
> Retrieve the status and results of a batch request
## GET /v1/batches/:id
Retrieve information about a specific batch, including its status and results.
## Authentication
Requires provider authentication headers:
```bash theme={null}
x-portkey-provider: openai
Authorization: Bearer YOUR_OPENAI_API_KEY
```
## Request
### Headers
The provider to route the request to (e.g., `openai`)
Bearer token for the provider API
### Path Parameters
The ID of the batch to retrieve
## Response
The batch identifier
The object type, always "batch"
The endpoint used for the batch
Error information if any requests failed
The ID of the input file
The completion time frame
The current status of the batch:
* `validating` - Checking the input file format
* `in_progress` - Processing the requests
* `finalizing` - Generating output files
* `completed` - All requests processed
* `failed` - Batch processing failed
* `cancelled` - Batch was cancelled
The ID of the file containing the outputs (available when status is `completed`)
The ID of the file containing errors (if any)
Unix timestamp of when the batch was created
Unix timestamp of when the batch started processing
Unix timestamp of when the batch completed
Statistics about the batch requests
Total number of requests in the batch
Number of successfully completed requests
Number of failed requests
Custom metadata attached to the batch
## Example
```bash cURL theme={null}
curl https://localhost:8787/v1/batches/batch_abc123 \
-H "x-portkey-provider: openai" \
-H "Authorization: Bearer $OPENAI_API_KEY"
```
```python Python theme={null}
from portkey_ai import Portkey
import time
client = Portkey(
provider="openai",
Authorization="sk-***"
)
# Poll for batch completion
batch_id = "batch_abc123"
while True:
batch = client.batches.retrieve(batch_id)
print(f"Status: {batch.status}")
if batch.status == "completed":
print(f"Batch completed!")
print(f"Output file: {batch.output_file_id}")
break
elif batch.status in ["failed", "cancelled"]:
print(f"Batch {batch.status}")
break
time.sleep(60) # Wait 1 minute before checking again
# Download results
if batch.status == "completed":
output_content = client.files.retrieve_content(batch.output_file_id)
with open("batch_results.jsonl", "wb") as f:
f.write(output_content)
```
```javascript JavaScript theme={null}
import Portkey from 'portkey-ai';
const client = new Portkey({
provider: "openai",
Authorization: "sk-***"
});
// Poll for batch completion
const batchId = "batch_abc123";
const checkBatch = async () => {
while (true) {
const batch = await client.batches.retrieve(batchId);
console.log(`Status: ${batch.status}`);
if (batch.status === "completed") {
console.log(`Batch completed!`);
console.log(`Output file: ${batch.output_file_id}`);
// Download results
const outputContent = await client.files.retrieveContent(batch.output_file_id);
// Process output content
break;
} else if (["failed", "cancelled"].includes(batch.status)) {
console.log(`Batch ${batch.status}`);
break;
}
await new Promise(resolve => setTimeout(resolve, 60000)); // Wait 1 minute
}
};
checkBatch();
```
### Response Example
```json theme={null}
{
"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": "file-err456",
"created_at": 1713894800,
"in_progress_at": 1713894900,
"completed_at": 1713898500,
"request_counts": {
"total": 100,
"completed": 98,
"failed": 2
},
"metadata": {
"description": "Daily batch job"
}
}
```
## Output File Format
Once the batch is completed, download the output file:
```json theme={null}
{"id": "batch_req_abc123", "custom_id": "request-1", "response": {"status_code": 200, "body": {"id": "chatcmpl-123", "object": "chat.completion", "created": 1713894800, "model": "gpt-4o-mini", "choices": [{"index": 0, "message": {"role": "assistant", "content": "2+2 equals 4."}, "finish_reason": "stop"}]}}, "error": null}
{"id": "batch_req_def456", "custom_id": "request-2", "response": {"status_code": 200, "body": {"id": "chatcmpl-456", "object": "chat.completion", "created": 1713894801, "model": "gpt-4o-mini", "choices": [{"index": 0, "message": {"role": "assistant", "content": "The capital of France is Paris."}, "finish_reason": "stop"}]}}, "error": null}
```
## Best Practices
Batch processing typically takes several hours. Implement polling logic with appropriate intervals (1-5 minutes) rather than continuous polling.
Use webhooks (if supported by your provider) to get notified when batches complete instead of polling.
## Related Endpoints
Create a new batch
Cancel a running batch
View all batches