OpenAI Batch API
Billed to the org that owns the API key in the batch-router accounts config ($BATCH_ACCOUNTS, default
~/.config/batch-router/accounts.toml). Treat it as pay-per-token unless that account says
credit_linked = true, which means the ChatGPT Pro credit is linked to the key's org; Batch draws it.
What this skill carries — grep references/ for any subject the names below miss:
!d=${CLAUDE_SKILL_DIR}; command -v skill-toc >/dev/null 2>&1 && exec skill-toc "$d"; s=$HOME/.claude/skills/plugin-utils/bin/skill-toc; [ -x "$s" ] && exec "$s" "$d"; echo "(skill-toc unavailable: references and scripts are NOT listed here — install the plugin-utils plugin, or start a new session so its bin/ reaches PATH)"
accounts prints pay-per-token for such an account: both commands then bill his card at list batch
price. Only validate, accounts and list are free. Running a "tiny" paid test because it costs a cent
decides a billing question that is his. The full run also waits for validate, verify and the pilot's
results --input to exit 0.
The sequence
S=${CLAUDE_SKILL_DIR}/scripts/openai_batch.py
uv run $S accounts # billing mode per account; free
uv run $S validate requests.jsonl # one model + one endpoint per file, limits; free
uv run $S list # existing batches; free
uv run $S verify requests.jsonl # ONE sync request at full price (go-ahead required)
uv run $S submit pilot.jsonl --run # Files upload + create; 5-10 rows first
uv run $S status <batch_id> --wait # in a background Bash
uv run $S results <batch_id> --input pilot.jsonl --out pilot.out.jsonl
Rows are {"custom_id", "method": "POST", "url": "/v1/responses", "body": {...}}. results merges the
output and error files and reconciles every custom_id; it exits 1 unless all succeeded. Check current
model ids and batch prices on the pricing page at use
time; the snapshot is in batch API reference.
Facts
- Pro credit (since 2026-10-28): $100 / $200 / $500 per month for the Pro 100/200/500 tiers. Eddy's
Codex auth reports
prolite, inferred to be the $100 tier, unconfirmed. The credit must be LINKED by
him to an API org he owns under the same email; issued per renewal, first one prorated, expires at cycle
end, no rollover, spends before purchased credit.
- Batch draws the credit (Eddy confirmed from the billing page, 2026-11-08: the Terra batches of
2026-11-06 came off it). The credits page itself never names Batch; for any other endpoint, check the
billing page before calling it free.
- Exhausted credit returns HTTP 429
credit_balance_exhausted; the script names it. Stop there and
report it; a retry loop on 429 just re-sends to an empty balance.
- Limits: 50,000 requests and 200 MB per input file, one model and one endpoint per file;
completion_window is only 24h; 2,000 batch creations per hour; per-model enqueued-token caps on the
org limits page. Over a limit: shard. PDFs past the cap: upload (purpose user_data) under the
SAME --account as submit and reference it as input_file (proven in a batch 2026-11-06) —
Files API.
- Output: out of order (match on
custom_id); failures go to error_file_id; expired rows carry
code batch_expired; output files are deleted 30 days after completion.
- Web search works in Batch:
tools=[{"type":"web_search"}] in a /v1/responses row searched and
returned url_citation annotations (verified live 2026-11-05, $10/1k searches); the router offers OpenAI
for --needs web-search.
- Turnaround is variable, and every job waits twice (pilot, then full batch): 2026-11-05 saw a 1-row
batch take ~4.8 h and, later, an 8-row pilot and a 79-row gpt-6.1-terra batch take ~40 min each; Claude's
finished in 2.5 min. Budget hours, not minutes; under ~100 rows, sync calls at 2x price or a Claude batch
are faster.
Red flags — STOP
| About to |
Do instead |
verify or submit --run while credit_linked = false |
Ask Eddy first; it bills his card |
| Mix two models or two endpoints in one file |
One file per model and endpoint |
Read only output_file_id |
results --input, which reads error_file_id too; done only on exit 0 |
Set credit_linked = true because the Pro plan includes credit |
Only once the API org's billing page shows the credit applied |
| Poll status from the model turn by turn |
status --wait in a background Bash, notified on exit |
1---2name: openai-batch3version: 1.04description: "Use when the user says 'OpenAI batch', 'GPT batch', 'OpenAI Batch API', 'submit an OpenAI batch', 'run this through GPT in bulk', 'use my ChatGPT Pro API credits', or when batch-router picked the OpenAI account."5user-invocable: false6metadata:7 source: https://skillmd.com/skills/edwinhu/openai-batch8---910# OpenAI Batch API1112Billed to the org that owns the API key in the batch-router accounts config (`$BATCH_ACCOUNTS`, default13`~/.config/batch-router/accounts.toml`). Treat it as **pay-per-token** unless that account says14`credit_linked = true`, which means the ChatGPT Pro credit is linked to the key's org; Batch draws it.1516**What this skill carries** — grep `references/` for any subject the names below miss:17!`d=${CLAUDE_SKILL_DIR}; command -v skill-toc >/dev/null 2>&1 && exec skill-toc "$d"; s=$HOME/.claude/skills/plugin-utils/bin/skill-toc; [ -x "$s" ] && exec "$s" "$d"; echo "(skill-toc unavailable: references and scripts are NOT listed here — install the plugin-utils plugin, or start a new session so its bin/ reaches PATH)"`1819<EXTREMELY-IMPORTANT>20## IRON LAW: NO `verify` OR `submit` WHILE `credit_linked = false` WITHOUT A YES FROM EDDY IN THIS SESSION2122`accounts` prints `pay-per-token` for such an account: both commands then bill his card at list batch23price. Only `validate`, `accounts` and `list` are free. Running a "tiny" paid test because it costs a cent24decides a billing question that is his. The full run also waits for `validate`, `verify` and the pilot's25`results --input` to exit 0.26</EXTREMELY-IMPORTANT>2728## The sequence2930```bash31S=${CLAUDE_SKILL_DIR}/scripts/openai_batch.py32uv run $S accounts # billing mode per account; free33uv run $S validate requests.jsonl # one model + one endpoint per file, limits; free34uv run $S list # existing batches; free35uv run $S verify requests.jsonl # ONE sync request at full price (go-ahead required)36uv run $S submit pilot.jsonl --run # Files upload + create; 5-10 rows first37uv run $S status <batch_id> --wait # in a background Bash38uv run $S results <batch_id> --input pilot.jsonl --out pilot.out.jsonl39```4041Rows are `{"custom_id", "method": "POST", "url": "/v1/responses", "body": {...}}`. `results` merges the42output and error files and reconciles every `custom_id`; it exits 1 unless all succeeded. Check current43model ids and batch prices on the [pricing page](https://developers.openai.com/api/docs/pricing.md) at use44time; the snapshot is in [batch API reference](references/batch-api.md).4546## Facts4748- **Pro credit (since 2026-10-28):** $100 / $200 / $500 per month for the Pro 100/200/500 tiers. Eddy's49 Codex auth reports `prolite`, inferred to be the $100 tier, unconfirmed. The credit must be LINKED by50 him to an API org he owns under the same email; issued per renewal, first one prorated, expires at cycle51 end, no rollover, spends before purchased credit.52- **Batch draws the credit** (Eddy confirmed from the billing page, 2026-11-08: the Terra batches of53 2026-11-06 came off it). The credits page itself never names Batch; for any other endpoint, check the54 billing page before calling it free.55- **Exhausted credit** returns HTTP 429 `credit_balance_exhausted`; the script names it. Stop there and56 report it; a retry loop on 429 just re-sends to an empty balance.57- **Limits:** 50,000 requests and 200 MB per input file, one model and one endpoint per file;58 `completion_window` is only `24h`; 2,000 batch creations per hour; per-model enqueued-token caps on the59 org limits page. Over a limit: shard. PDFs past the cap: `upload` (purpose `user_data`) under the60 SAME `--account` as `submit` and reference it as `input_file` (proven in a batch 2026-11-06) —61 [Files API](references/batch-api.md#files-api-documents-by-file_id).62- **Output:** out of order (match on `custom_id`); failures go to `error_file_id`; expired rows carry63 code `batch_expired`; output files are deleted 30 days after completion.64- **Web search works in Batch:** `tools=[{"type":"web_search"}]` in a `/v1/responses` row searched and65 returned `url_citation` annotations (verified live 2026-11-05, $10/1k searches); the router offers OpenAI66 for `--needs web-search`.67- **Turnaround is variable, and every job waits twice** (pilot, then full batch): 2026-11-05 saw a 1-row68 batch take ~4.8 h and, later, an 8-row pilot and a 79-row gpt-6.1-terra batch take ~40 min each; Claude's69 finished in 2.5 min. Budget hours, not minutes; under ~100 rows, sync calls at 2x price or a Claude batch70 are faster.7172## Red flags — STOP7374| About to | Do instead |75|---|---|76| `verify` or `submit --run` while `credit_linked = false` | Ask Eddy first; it bills his card |77| Mix two models or two endpoints in one file | One file per model and endpoint |78| Read only `output_file_id` | `results --input`, which reads `error_file_id` too; done only on exit 0 |79| Set `credit_linked = true` because the Pro plan includes credit | Only once the API org's billing page shows the credit applied |80| Poll status from the model turn by turn | `status --wait` in a background Bash, notified on exit |