Batch API
The Batch API lets you submit up to 100,000 requests in a single call (max 256 MB per batch).- Submit a batch. Send all your requests in one
POST /batchescall. - Poll for status. Check
GET /batches/{batch_id}until all requests are completed. - Retrieve results. Fetch individual results via
GET /batches/{batch_id}/{custom_id}.
GET /batches.
Attach an Idempotency-Key header on submission so a client retry after a network blip replays the original batch reservation instead of creating a duplicate. See Idempotent Requests.
Batch items default to
metadata.completion_window: "balanced" when the field
is omitted. If you set it explicitly, it must be either "balanced" or
"flex". Other values are rejected for batch items. For low-latency
workloads, use the Responses API
instead. See Completion Windows for the full tier
definitions and per-model availability.Python example
First, install therequests library:
Responses API with background mode
You can also submit requests individually using the Responses API withbackground=True. For large-volume workloads (1,000+ requests), we recommend:
- Use
AsyncOpenAIwithDefaultAioHttpClient(). The OpenAI SDK’s built-in aiohttp client is more efficient than the defaulthttpxbackend for high-concurrency workloads. - Gate concurrency with an
asyncio.Semaphore. This gives you fine-grained control over how many simultaneous connections are opened (e.g. 200), preventing connection exhaustion. - Submit all requests concurrently with
background=True, then poll. Fire off all submissions in parallel (gated by the semaphore), collect the response IDs, and poll for completions in a separate loop. - Send a per-request
Idempotency-Keyso a retry after a transient failure replays the reservation instead of duplicating inference work. See Idempotent Requests.