Batch API

Upload, create, poll, download

import os
from openai import OpenAI

client = OpenAI(base_url="https://gridport.ai/v1", api_key=os.environ["GRIDPORT_API_KEY"])

f = client.files.create(file=open("requests.jsonl", "rb"), purpose="batch")
b = client.batches.create(input_file_id=f.id, endpoint="/v1/chat/completions", completion_window="24h")
# … later
b = client.batches.retrieve(b.id)              # validating → in_progress → completed
if b.status == "completed":
    out = client.files.content(b.output_file_id).text   # one JSON line per request, in input order

Each input line is {"custom_id", "method": "POST", "url", "body"}; url is one of /v1/chat/completions, /v1/embeddings, /v1/responses or /v1/messages and every line in a batch must use the batch's endpoint. Output lines carry {"custom_id", "response": {"status_code", "request_id", "body"}}. Requests that failed land in the error file with the error code.

Stored responses (store, background, conversation) are not available in batches: a line that sets store: true, background: true, previous_response_id or conversation fails with permission_denied. Send those requests to /v1/responses directly.

Send an Idempotency-Key header (1–128 characters) with batches.create to retry it safely: for 24 hours the same key and body return the first batch instead of creating, running and charging a second one, and the same key with a different body is refused with 409. A retry made after rotating the API key finds the same batch. Cancelling stops the lines that have not started: request_counts.cancelled counts them and the error file lists them with the code batch_cancelled. They are not charged.

Price, limits, guarantees

Batch requests are billed at the batch tier: half the standard input and output price unless the model page lists an explicit batch price. Files are limited to 10 000 lines / 100 MB. Input retention must cover the full completion window. Actual expiry follows project policy and the file expires_at; it is not a fixed 30 days. Output expiry is calculated at generation and capped by the originating data-retention deadline. A batch that does not finish inside 24 hours is marked expired — finished lines are delivered and billed, unfinished ones are not. Cancel at any time; completed work is kept. Every request appears in the log with source = batch and the batch id, and counts toward budgets like any other call.

# BATCH is the id returned by batches.create
curl https://gridport.ai/v1/batches/$BATCH -H "Authorization: Bearer $GRIDPORT_API_KEY"
# "request_counts": {"total": 10000, "completed": 9998, "failed": 2, "cancelled": 0}, "tf": {"pricing_tier": "batch", "cost": "1.234567"}