Adopting the Message Batches API: Habits That Stick

A new API capability is easy to demo and hard to institutionalize. I have watched teams discover Anthropic's Message Batches API, get excited about the 50% cost reduction, run one impressive proof-of-concept, and then quietly drift back to synchronous calls for everything because batching never became a habit. The technical part — submit, poll, read results — takes an afternoon to learn. The organizational part — making asynchronous inference the default mental model for the right class of work — takes deliberate change management. This post is about that second part: the norms, rituals, and small structural nudges that get a team to actually reach for batching when it is the right tool, instead of defaulting to the synchronous call they already know.

Key takeaways

• Adoption fails on defaults and mental models, not on API difficulty — engineers reach for the synchronous call out of habit.
• Make the latency-tolerant/latency-sensitive distinction an explicit, written norm so it shows up in design review.
• Wrap the batch lifecycle in a small internal helper so submitting a batch is as easy as a synchronous call.
• Track a single team metric — share of eligible volume that runs through batches — to make drift visible.
• Change management here is mostly about removing friction, not adding mandates.

Why teams default away from batching

The synchronous Messages API has a tight feedback loop: you call it, you get an answer, you iterate. The Batches API has a deferred loop: you submit, you wait, you come back. For an engineer prototyping under pressure, the synchronous loop wins every time because it matches the rhythm of their work. The result is a quiet anti-pattern — workloads that are obviously latency-tolerant (nightly enrichment, bulk re-classification, eval runs) get shipped on the synchronous path simply because that is the path the engineer was already in.

This is not an education problem you solve with one lunch-and-learn. It is a defaults problem. The fix is to make the batch path feel as low-friction as the synchronous path for the work where it belongs, and to put a checkpoint in your process where someone asks "does this need to be synchronous?" before the synchronous version becomes load-bearing.

The one norm worth writing down

Most of the organizational value comes from a single, explicit rule that lives in your engineering handbook and gets referenced in design review: if no human or downstream system is blocked waiting on the result within minutes, it is a batch candidate. That sentence does more for adoption than any amount of tooling, because it converts a vague "we should use batches more" into a concrete question with a yes/no answer that a reviewer can ask.

The flowchart below is the decision your team should be able to run in their heads — and that a design-review template should force them to answer.

flowchart TD
  A["New Claude workload"] --> B{"Human waiting on the result?"}
  B -->|Yes| C["Synchronous Messages API"]
  B -->|No| D{"Volume > a few hundred/day?"}
  D -->|No| C
  D -->|Yes| E{"Result needed within minutes?"}
  E -->|Yes| C
  E -->|No| F["Batch candidate — flag in design review"]
  F --> G["Submit via shared batch helper"]

The point of writing it down is not bureaucracy. It is that a norm nobody can quote is a norm nobody follows. When the question "is this a batch candidate?" is a standing item on your design-doc template, batching stops depending on whichever engineer happens to remember it exists.

Remove the friction with a shared helper

The single highest-leverage change-management move is to make submitting a batch feel like one function call. If every engineer has to remember the Request shape, the polling loop, and the result-handling enum, the synchronous path will always win on ergonomics. So you build a thin internal wrapper once and everyone uses it. Something like this becomes the team's default for bulk work:

def run_batch(items, build_params, poll_seconds=30):
    """Submit, wait, and return {custom_id: text} for a list of items."""
    requests = [
        Request(custom_id=str(i), params=build_params(item))
        for i, item in enumerate(items)
    ]
    batch = client.messages.batches.create(requests=requests)
    while client.messages.batches.retrieve(batch.id).processing_status != "ended":
        time.sleep(poll_seconds)
    out = {}
    for r in client.messages.batches.results(batch.id):
        if r.result.type == "succeeded":
            msg = r.result.message
            out[r.custom_id] = next((b.text for b in msg.content if b.type == "text"), "")
    return out

Now the cognitive cost of choosing the batch path drops to nearly zero. An engineer who decides a workload is latency-tolerant calls run_batch(records, build_params) and is done. That ergonomic parity is what makes the written norm actually get followed — you have aligned the easy path with the correct path.

Make drift visible with one metric

Habits decay silently. The way you catch decay is to instrument it. Pick one number and put it on a dashboard the team sees: the share of eligible token volume (latency-tolerant, high-volume work) that actually ran through batches last month. You will never hit 100% and should not try — eligibility is a judgment call — but a steady or rising share means the norm is sticking, and a falling share is an early signal that people are quietly defaulting back to synchronous calls.

This metric also reframes the conversation in a healthy way. Instead of nagging individuals, you look at a trend line in a retro and ask what made the synchronous path more tempting this month. Usually the answer points at a friction source you can remove — a missing helper feature, an unclear norm, a deadline that made waiting feel risky.

A rollout sequence that actually lands

1. Pick one obviously-eligible workload (a nightly enrichment job or an eval suite) and migrate it to batches as a visible reference implementation.
2. Build the shared run_batch helper from that migration so the second team to adopt starts from working code.
3. Add the "is this a batch candidate?" question to your design-doc and PR review templates.
4. Write the latency-tolerant norm into the engineering handbook in one sentence, and link it from the template.
5. Instrument the eligible-volume-through-batches metric and review it in the monthly engineering retro.
6. Celebrate the cost win publicly the first time the dashboard moves — social proof drives adoption harder than mandates.

Common pitfalls

• Mandating batching by policy. A blanket "always batch when you can" rule with no helper and no metric produces resentment and quiet non-compliance. Reduce friction first; the behavior follows.
• Leaving the polling loop to each engineer. If everyone reimplements the submit-poll-read cycle, you get five subtly different, subtly buggy versions. Centralize it once.
• Ignoring the result-handling discipline. Teams that adopt batches but never standardize on persisting results before the 29-day expiry eventually lose a batch and blame the API. Bake result persistence into the shared helper.
• Treating adoption as a one-time event. Without the visibility metric, batch usage spikes after the kickoff and decays over the next two quarters. Habits need a feedback signal to survive.
• Forgetting the new-hire path. An engineer who joins six months after rollout never saw the kickoff. The norm has to live in the handbook and the templates, not in one team's memory.

Frequently asked questions

How do we decide which workloads are batch candidates?

Use one test: is anything blocked waiting on the result within minutes? If a human or a downstream synchronous system needs the answer fast, keep it synchronous. If the result can land within the hour-to-24-hour window the Batches API provides, and the volume is more than a few hundred requests, it is a batch candidate. Encode that test in your design-review template so it gets asked every time.

Should we force all eligible work onto batches?

No. Forcing creates friction and resentment. The durable approach is to make the batch path as ergonomic as the synchronous path with a shared helper, write down the eligibility norm, and track adoption as a trend rather than a quota. Behavior change driven by removed friction outlasts behavior change driven by mandate.

What is the single most effective adoption move?

Building the thin internal wrapper that makes submitting a batch one function call. Most non-adoption is ergonomic: the synchronous call is easier in the moment, so it wins. Erase that ergonomic gap and the written norm starts being followed on its own.

How do we keep adoption from decaying over time?

Instrument it. Put the share of eligible volume running through batches on a dashboard and review it in retros. A falling number is an early warning that friction has crept back in, and it points you at the specific thing to fix.

Bringing agentic AI to your phone lines

The same change-management discipline that gets a team using batched inference well is what makes any agentic system stick. CallSphere brings these voice and chat agents to your front line — answering every call, using tools mid-conversation, and booking work 24/7. See it live at callsphere.ai.

---

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.