Custom ID for Batch Correlation in the Claude Batches API

Why custom id for batch correlation exists

Custom id for batch correlation is the discipline that keeps an asynchronous batch from turning into an unmatched pile of answers. When you submit a synchronous request you get its answer back immediately, so there is never any doubt about which input produced which output. A batch breaks that one-to-one immediacy: you hand over thousands of requests at once, the system processes them independently, and the results file you download later can list them in any order. The model never sees a row number, and the API makes no promise to preserve input order, so without a deliberate key you cannot tell which generated summary belongs to which document.

The custom_id field is that key. You assign a unique string to every request in the batch, and the API echoes the exact same string back on the corresponding result. Joining outputs to inputs then becomes a straightforward lookup on that field. For the Claude Certified Architect exam this is an apply-level skill: you are expected to recognise that order is not guaranteed and to reach for custom_id as the correlation mechanism, not to recite its JSON schema.

Results come back in any order

The single fact that motivates this whole knowledge point is that batch results are unordered. Anthropic's documentation is explicit that results may not match the ordering of the requests when the batch was created, and that you should always use the custom_id field to match results to their requests. The reason is mechanical: each request is processed independently and finishes whenever it finishes, so a short request submitted last can complete before a long request submitted first. The results file simply records them in completion order, which is effectively arbitrary from your point of view.

This is why an architect who tries to zip the results array against the input array by position will silently corrupt their data. The first line of the results file is not the first request; it is just the first one that finished. The only correct join is on custom_id, and the only way that join works is if you assigned the ids carefully when you built the batch. You can confirm the unordered behaviour in Anthropic's batch processing guide.

Design the id, do not just generate one

The temptation is to assign throwaway ids like a random UUID or a simple counter. That technically satisfies uniqueness, but it wastes the field. A far better practice is to encode a stable business key from your own data into the custom_id, so the join back to your records needs no separate mapping table. If you are classifying support tickets, use the ticket id. If you are enriching CRM rows, use the row's primary key. If you are summarising documents, use a document identifier, perhaps with a stage suffix when one record fans out into several requests.

Two constraints shape the id you choose. It must be unique within the batch, because a duplicate id makes two results indistinguishable, and it must fit the format: 1 to 64 characters using only letters, numbers, hyphens, and underscores. That rules out raw file paths with slashes, email addresses with at-signs, or anything with spaces, so you sanitise the business key before using it. A meaningful, well-formed id turns result handling into a one-line lookup and, as the next knowledge point shows, makes failure handling almost free.

• Unique within the batch: never reuse an id, or two results collide.
• Format-safe: 1 to 64 characters, letters, numbers, hyphens, underscores only.
• Meaningful: encode a real key from your data so no side mapping is needed.
• Stable: derive it from the source record, not from request position.

How correlation enables failure handling

Correlation is not only about success; it is the foundation for recovery. Every batch result, whether succeeded, errored, canceled, or expired, carries its custom_id. That means the moment you read the results you can partition them by outcome and, for anything that did not succeed, produce an exact list of which inputs to revisit. Because one request failing never affects the others, you can resubmit just that list rather than rerunning the whole batch. This is the bridge from this knowledge point into batch failure handling and retry, where the partition-and-resubmit pattern is developed in full.

It is also why correlation is treated as an apply-level competency rather than trivia. The id you assign at submission time determines how cleanly you can read results, how precisely you can recover from failures, and whether your data stays trustworthy. A sloppy id scheme makes every downstream step harder; a thoughtful one makes them nearly automatic.

What goes wrong when you skip correlation

It is worth dwelling on the failure mode, because its danger lies in how quietly it strikes. A pipeline that matches results to inputs by position does not crash, throw an error, or leave any gap. Every input receives a result, every record is populated, and every dashboard turns green. The damage is entirely in the pairing: summaries attached to the wrong documents, classifications filed against the wrong customers, extracted figures written to the wrong rows. Nothing alerts you, because from the system's point of view nothing failed. The corruption can sit undetected until someone downstream notices that a contract's summary describes a different contract entirely, by which point the bad data may have spread through reports and decisions.

That silent quality is what makes correlation a correctness requirement rather than a nicety. Most bugs announce themselves; this one hides inside plausible-looking output. The only defence is to never rely on order in the first place, and to treat the echoed identifier as the single source of truth for which result belongs to which input. An architect who has seen this failure once never matches by position again, and the exam expects you to recognise the trap without having to be burned by it.

Composing ids that stay unique and meaningful

As workloads grow, a flat identifier scheme starts to strain, and a little structure pays off. A common pattern is to namespace the identifier so it stays unique even when several jobs or stages share a results store: a date or run prefix, then the record key, then an optional stage suffix when one source record fans out into several requests. A document split into three chunks might carry ids that pair the document key with a part number, so each chunk is independently addressable yet still obviously belongs to the same source. The only hard rules are that the whole string stays within the format, letters, numbers, hyphens, and underscores up to 64 characters, and that it remains unique within the batch.

Designing ids this way also makes reruns clean. Because the identifier is derived from stable source keys rather than from submission position, a resubmitted request can carry the very same id it had the first time, so its eventual result still lands on the right record without any special handling. That idempotent quality, where the same input always maps to the same identifier, is what lets correlation and recovery compose so smoothly into the larger pipeline, and it is why thoughtful id design repays the small effort it costs up front.

The batch ID and the custom_id do different jobs

When you correlate at scale it helps to keep two identifiers straight, because they answer different questions. The batch itself has a job-level identifier, returned when you create it, that names the whole submission: you use it to poll status, list a batch, fetch its results file, or cancel it. The custom_id lives one level down, on each request inside that batch, and names a single item. The job ID tells you which run you are looking at; the custom_id tells you which record a given result belongs to.

A robust pipeline persists both alongside its source data. Storing the job ID lets you find and re-fetch the correct results file later, even across many concurrent runs, while the custom_id lets you join each line of that file back to the exact input. Confusing the two, or storing only the job ID, leaves you able to locate a batch but unable to say which document any particular answer describes, which is precisely the alignment problem correlation exists to prevent.

How this knowledge point shows up on the exam

Questions on correlation usually describe a batch whose results are being mishandled and ask you to spot the flaw or choose the fix. The wrong answers lean on positional matching ("read the results in order") or on reprocessing everything when a few items fail. The right answers always route through custom_id: use it to join results to inputs, and use it again to isolate failures. If a scenario hints that results "came back in a different order," that is the examiner signalling this exact knowledge point, and the correct response is to correlate on the id rather than the index.

Watch and learn

Official Anthropic Academy lessons first, then hand-picked walkthroughs. Videos load only when you press play.

Stevan Freeborn

Message Batches API | Working on AnthropicClient

Why watch: Implements batch request submission and result retrieval against the AnthropicClient, exposing how each request carries a custom_id used to correlate responses back to inputs since batch results are not order-guaranteed.