Sync or batch

Who is waiting decides the path

Claude answers in one of two ways. The Messages API answers in the same call. The Batches API takes a list of requests, each with a custom_id, and answers later at half the price.

The plan decides the path, and the API runs it. A plan that picks wrongly fails in three ways.

A blocking check waits on a batch. A nightly job pays full price. A failed batch is rerun whole. The first two fail in a recorded run, and the third shows in the code and the fixed run.

A blocking check answers in the same call

The merge check is a job someone waits on, so the plan runs it sync. The request goes to the Messages API and the reply comes back in the same call. Open the card to read what Claude answered.

This is a real Claude Haiku 5.5 call, recorded once and replayed here. Nothing about it depends on how large the change is.

The starting plan sends the check to a batch

mode picks the path for a job, and resubmit picks what to send again. The starting mode has the rule backwards: it sends the blocking job to a batch and runs the overnight jobs sync.

The starting resubmit returns every custom_id, so one failed result sends the whole batch again.

The price is what makes this tempting. A batch costs half as much, so a check that runs on every change looks like the place to save. But a batch trades a wait for that price, and this check cannot wait.

How long will the merge check wait?

The starting plan has sent the merge check to the Batches API. A developer has pushed a change and is watching the merge button.

The merge waits for a batch

The plan chose batch, so the check was submitted as a request with a custom_id and a batch to poll. The outcome line is the cost: the developer waits on a path with no latency promise. The last call sends the batch's one request again, because the starting resubmit returns every custom_id.

A batch may end sooner than its window, but nothing promises it. The window is up to 24 hours, and the API does not say when inside it.

Sync for blocking work, batch for the night

The fixed mode asks one question: is someone waiting? If so it runs sync. If not it runs batch, whatever the size of the job. The fixed resubmit reads each result's type and returns the custom_id of every result that did not succeed.

Follow the arrows. The expired result is matched to its request by custom_id, and only that request goes again. A batch whose results all succeeded sends nothing.

The same jobs, two plans

Switch between the starting plan and the fixed plan on the merge check. The card marked "This is where the runs split" is the plan's choice. One path answers now and the other answers later.

Then pick the nightly jobs. The starting plan runs them sync at full price, and the fixed plan runs them as a batch at half price.

Size does not decide the mode

Both nightly jobs are overnight work, 12 tickets and 10,000 orders. Both cards use the fixed plan, and the large one goes to a batch too. It is not special, because nobody is waiting on either.

Work out the window from the deadline. A batch ends within 24 hours, so it fits a report due in 30 hours and not one due in 6. Before a full run, tune the prompt on a small sample. A bad prompt on the whole job is paid for in full.

Try it: plans and jobs

Pick the starting plan on the merge check to see the wait, or on a nightly job to see the full price. Pick the fixed plan on the nightly tags to see one result sent again alone. The harness simulates that expired result, and only the resend is a recorded call.

Every combination is a recorded run, so this works with no internet.

The sync path in the Agent SDK

The Claude Agent SDK answers now, so it is the sync path. It has no batch. Each batch request is a single Messages call, so a multi-turn tool loop cannot run inside it.

For a CI job, claude -p is the same sync path from the command line. It runs once, prints its result, and lets the job read it. This is a real Claude Haiku 5.5 run.

You do: pick the path and resend

Copy the starting code and open work/sync-or-batch/plan.py. mode() sends overnight jobs down the sync path, and resubmit() sends every result again.

./workshop start sync-or-batch
./workshop check sync-or-batch
./workshop watch sync-or-batch

The checks want a blocking job on sync and a nightly job on batch, whatever its size. Only results that did not succeed are sent again, by custom_id.

Check your understanding

Answer each question, then read why every option is right or wrong. The wrong options are the mistakes engineers make on the job.

Play: predict the output

This rule picks the path by how many requests a job sends.

def mode(job: Job) -> str:
    return "sync" if job.size < 100 else "batch"

References

• Batch processing: result types, the 24-hour window and how custom_id maps results back.
• Run Claude Code headless: the sync path a waiting person needs.
• Pricing: what the batch discount saves on a nightly job.

Conclusions

• A job someone waits on runs sync. A batch has no latency promise.
• Overnight work runs batch at half price, whatever its size.
• A failed result is found by its custom_id and sent again alone.

You can now choose sync or batch for a job from who is waiting, and recover a batch by custom_id.