Claude and the Anthropic SDK (TypeScript) · Chapter 17 of 21
Message Batches
By the end of this chapter you can send hundreds of requests to Claude as one Message Batch at half the price, wait for it the right way, read its results whatever order they come back in, find the requests that failed and send only those again, and say when a batch is the wrong choice. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: Cost
- 4 tasks
- TypeScript
- In the all labs plan
The first 2 chapters of Claude and the Anthropic SDK (TypeScript) are free. This one comes with the all labs plan.
Why you need this
Every evening Parchi's WhatsApp inbox holds about sixty messages from families: "CLM-2402 ka status kya hai?", "What documents do I need?", "Pre-authorisation was rejected at the hospital desk". Kamla's team sorts them into seven piles before anyone answers, so the claim-status questions go to one person and the appeals to another. Sorting by hand takes an hour a day.
Sahay can sort them. You could loop over the sixty and call messages.create for each, as you have done all along. But nobody is waiting for these answers: the families wrote hours ago, and the team reads the piles tomorrow morning. Farhan has noticed. "If nobody is waiting, why are we paying for an answer in two seconds?"
Claude's API has an answer to that: the Message Batches API. You hand it many ordinary requests at once, it works through them in its own time, and it bills every token at half the price. The catch is the other side of the same coin: you do not get the answers back one by one, in order, at once. A batch is a job you start, check on, and collect, and the code that collects it has to be written for that.
What you build: 4 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
inbox-batch.ts: the inbox as one batch
Send the 60 inbox messages as ONE batch with client.messages.batches.create: one request per message, custom_id the message's id, params with model 'claude-haiku-5-5', max_tokens 1024, system: SORT (given) and the message's text as the one user message.
Print batch: ID and status: STATUS (as created). Then retrieve the batch once a second until its processing_status is 'ended', and print status: ended and succeeded: S, errored: E from its request_counts.
- Task 2
by-custom-id.ts: match the results by custom_id
Export async classify(messages): one batch for the messages (as task 1), waited for until it ends, then its results read with client.messages.batches.results(id), returned as a Map from message id to label: a succeeded result's text, trimmed; anything else 'unknown'.
Under if (import.meta.main), classify the whole inbox and print ID: LABEL for every message in the inbox's order, then right: N/60. The check also classifies twelve messages in an order of its own.
- Task 3
resend-errored.ts: errored requests, fixed and sent again
Send REQUESTS (given) unchanged as one batch, wait for it, then print first batch: S succeeded, E errored and ID: errored, TYPE for each errored request in REQUESTS order (TYPE is result.error.error.type).
Fix only those (model 'claude-haiku-5-5', no temperature), send them again as a second batch with the same custom_ids, wait, and print second batch: S succeeded, E errored, then ID: LABEL for all six in REQUESTS order.
- Task 4 · interview question
Interview: three-ways.ts
"Do batches and caching really change the bill?" Ask the 8 QUESTIONS (given) with MODEL, max_tokens 1024, three ways: in real time with messages.create and system: SYSTEM; as one batch with system: SYSTEM; as one batch with system as one text block of SYSTEM with cache_control: { type: 'ephemeral' }.
Price every reply from its usage (input, cache writes at cache_write_5m, cache reads, output, at PRICES[MODEL]), batch replies times BATCH_DISCOUNT, and print real time: $A, batch: $B, batch and cache: $C (6 decimals) and saved: P% (1 - C / A, rounded).
What you will learn
- A batch: a list of ordinary Messages requests, each with a custom_id, sent with client.messages.batches.create.
- Its life: in_progress, then ended; polling with retrieve; request_counts; cancelling.
- Results: batches.results(id), one line per request, in any order, matched by custom_id.
- Errors in a batch: succeeded, errored, canceled, expired, and sending only the failed requests again.
- What it costs: service_tier: 'batch', half price on every token, and the cache inside a batch.
More in Cost
Build "Message Batches" yourself
Parchi, a Jaipur startup, helps families claim health insurance. You build Sahay, a claims assistant that reads bills and policies with Claude, and measure what caching, models and effort cost. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.
The first 2 chapters of Claude and the Anthropic SDK (TypeScript) are free. This one comes with the all labs plan.