Keep blocking work on synchronous Messages

Learning objective

Select synchronous Messages requests for blocking workflows and Message Batches for asynchronous, latency-tolerant work.

Core idea

Choose the execution path from the consequence of waiting. A pre-merge review holds a developer’s change until findings arrive. A weekly audit can collect findings before someone reads them. These workflows can use the same prompt and still need different API paths.

Use a synchronous Messages request when the next application action depends on the response. Use Message Batches when you can submit independent work, release the caller, and consume the results later. The batch discount is useful only after the workflow passes that latency test. A cheaper result that arrives after the decision it supports has lost its value.

This lesson owns that selection decision. See 4.5.2 for pricing and execution constraints, 4.5.3 for delivery planning, and 4.5.4 for matching and recovering individual results. The distinction between an asynchronous SDK client and deferred batch processing is covered in 0.4.

How it works

Follow the dependency to its consumer

Use POST /v1/messages to generate the next assistant message from your supplied conversation. Your CI job receives that message as the synchronous request’s result and examines it before deciding whether the merge check passes. Define how your job handles failures or excessive waiting: choosing synchronous Messages does not itself guarantee an application deadline.

For a deferred report, submit a requests list to POST /v1/messages/batches. Put each message request inside its entry’s params, beside its custom_id. Your submission job receives a batch identifier, rather than completed assistant messages. Retrieve the results after the independently processed entries reach the batch’s terminal state.

Your submission job can exit while the batch is processing. Have your report job read the results and publish them later, according to the report’s delivery policy. Show a pending outcome wherever someone checks progress; the submission receipt identifies deferred work, not a completed report.

Separate volume from urgency

A large workload does not automatically belong in a batch. A pre-merge gate reviewing many changed files is still blocking if the merge waits for the findings. Conversely, a small weekly audit can be latency-tolerant even when it contains only a few requests. Request count affects the economics and operation of batching; it does not decide whether delay is acceptable.

Classify the consumer’s requirement before grouping work. Ask whether a delayed response prevents a person or pipeline from proceeding, whether the consumer has a real delivery cutoff, and whether incomplete work has an acceptable deferred outcome. An overnight label alone is insufficient. A report that must pass before a morning release has a blocking deadline, even though it runs at night.

Batches suit large-scale evaluations and analyses that do not require immediate results. The documentation also permits different request types in one batch because entries are processed independently. That flexibility does not establish dependencies between entries. If one analysis needs another analysis’s output, supply the needed evidence first or schedule a later request after the prerequisite result exists.

Prepare self-contained work

A batched message still needs the instructions and evidence required for its own result. For nightly test-gap analysis, that can mean one request containing a module’s source and relevant tests. The batch submission is a collection of message requests, not a shared conversation in which every entry automatically receives the output of previous entries.

An interactive agent that must inspect files or execute application tools during its work has a different execution shape. Keep the application-controlled interaction on the Messages path, or split it into separately orchestrated stages. See 4.5.2 for the distinction between client tools and server tools; the mere appearance of tools in a request does not settle the choice.

Key distinctions and trade-offs

The following comparisons keep the selection focused on the workload:

Polling detects the batch’s state; it does not change the consumer’s requirement. Adding frequent polls to a blocking pre-merge batch leaves the developer waiting for deferred processing. A synchronous fallback can be part of a deliberate delivery design, but it does not make batching the natural default for every interactive operation.

Similarly, unordered results are an integration requirement, not a reason to reject batching for eligible work. custom_id provides correlation; see 4.5.4. Choose the execution model first, then implement its result handling.

Architecture / decision scenario

A developer-productivity service performs two reviews. For each pull request, it checks whether the proposed code introduces a release-blocking defect. Each weekend, it also reviews merged modules for missing tests. An engineer proposes moving both workloads to Message Batches to reduce inference spending.

Keep the pre-merge review on POST /v1/messages. The merge check consumes the assistant response during the active operation, so deferred completion conflicts with its purpose. Do not replace this path merely because the service already has a background worker or can poll a batch ID.

Move the weekend analysis to POST /v1/messages/batches if its publication policy accepts delayed or incomplete work. Supply each module’s evidence in its entry’s params, retain the returned batch ID, and let the report job consume results later. Use the scheduling analysis in 4.5.3 if the team adds a firm publication target.

If the same team introduces a mandatory test-gap verdict before every release, reconsider that workload’s classification. Its prompt has not changed, but its consumer now blocks. API selection follows that changed dependency rather than the historical name of the job.

Common exam traps

• Moving every high-volume workflow to batches without checking who waits for the result.
• Treating an asynchronous SDK call as equivalent to deferred Message Batches processing.
• Assuming that a nightly job has no delivery deadline.
• Keeping eligible background analysis synchronous because batch results can be unordered.
• Treating a batch receipt as the completed analysis.
• Assuming that selecting synchronous Messages alone guarantees an application latency target.

What to remember

Choose synchronous Messages when the response is needed to continue the active workflow. Choose Message Batches when independent work can finish later and the consumer accepts that lifecycle. Classify the dependency before considering the discount, and revisit the choice when a background report becomes a blocking gate.

Knowledge check

References

• Anthropic, Create a Message
• Anthropic, Batch processing