CCA-FChapters07

Chapter 07

Message Batches API

Half price, a 24-hour ceiling that is not an SLA, and no tool loops. Plus surgical recovery via custom_id.

D4guide part i

7.1

Four facts, and they decide every question

Asynchronous processing of many independent requests, at half price, with no latency promise.

50% cheaperversus the same requests sent synchronously
up to 24 hoursa processing window, not an SLA — no latency guarantee inside it
no multi-turn toolsone request → one response. A tool-use loop cannot run here
custom_idyour own key on each request, echoed on each result
The third row is the one people forget: a batch request is one shot, not a conversation.

7.2

Batch or synchronous

One question decides it: is somebody waiting for this right now?

taskapiwhy
pre-merge PR checksynchronousthe developer is blocked; 24 hours is absurd
interactive code reviewsynchronousimmediate response required
overnight tech-debt reportbatchneeded by morning, and half the cost
weekly security auditbatchnot urgent, runs on a schedule
10,000 documentsbatchbulk work — the saving is the point

7.3–7.4

custom_id earns its keep on failure

Partial failure is the normal case at volume. The id is what makes recovery surgical.

submit 100one custom_id eachprocessingup to 24h95 complete5 failedcontext limit exceededchange strategy, resubmit those 5chunk the long documents · identified by custom_id
Only the failures are re-submitted — successful documents are never paid for twice.

7.5

Work backwards from the deadline

The 24-hour window is a ceiling you must subtract, not an estimate you can hope beats itself.

submit: 6hbatch window: up to 24hnow+6h · last safe submit+30hdeadline30 − 24 = 6 · frequent runs → split into 4h submission windows
Need it in 30 hours? You have 6 hours to submit. Miss that and the deadline is no longer guaranteed.

Recall in 60 seconds

  1. Batch = 50% cheaper, up to 24h window, no latency SLA.
  2. One request → one response. Multi-turn tool calling is not supported in batches.
  3. Anything a human is waiting on stays synchronous — pre-merge checks, interactive review.
  4. Overnight reports, scheduled audits and bulk document runs are what batch is for.
  5. custom_id links each result to its source document.
  6. On partial failure, identify by custom_id and resubmit only the failures.
  7. Fix the cause before resubmitting — e.g. chunk documents that blew the context limit.
  8. Submission cut-off = deadline − 24h. Never plan on finishing early.