Retrieve Batch

GET /v1/batches/:id

Retrieve information about a specific batch, including its status and results.

Authentication

Requires provider authentication headers:

x-portkey-provider: openai
Authorization: Bearer YOUR_OPENAI_API_KEY

Request

Headers

string

required

The provider to route the request to (e.g., openai)

string

required

Bearer token for the provider API

Path Parameters

string

required

The ID of the batch to retrieve

Response

string

The batch identifier

string

The object type, always “batch”

string

The endpoint used for the batch

object

Error information if any requests failed

string

The ID of the input file

string

The completion time frame

string

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

string

The ID of the file containing the outputs (available when status is completed)

string

The ID of the file containing errors (if any)

integer

Unix timestamp of when the batch was created

integer

Unix timestamp of when the batch started processing

integer

Unix timestamp of when the batch completed

object

Statistics about the batch requests

Show request_counts object

integer

Total number of requests in the batch

integer

Number of successfully completed requests

integer

Number of failed requests

object

Custom metadata attached to the batch

Example

curl https://localhost:8787/v1/batches/batch_abc123 \
  -H "x-portkey-provider: openai" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

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)

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

{
  "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:

{"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.

Create Batch

Create a new batch

Cancel Batch

Cancel a running batch

List Batches

View all batches

Overview

Models

Messages

Chat

Completions

Embeddings

Images

Audio

Files

Batches

Fine-tuning

Realtime

GET /v1/batches/:id

Authentication

Request

Headers

Path Parameters

Response

Example

Response Example

Output File Format

Best Practices

Create Batch

Cancel Batch

List Batches

​GET /v1/batches/:id

​Authentication

​Request

​Headers

​Path Parameters

​Response

​Example

​Response Example

​Output File Format

​Best Practices

​Related Endpoints

Create Batch

Cancel Batch

List Batches

GET /v1/batches/:id

Authentication

Request

Headers

Path Parameters

Response

Example

Response Example

Output File Format

Best Practices

Related Endpoints