custom_id

When you submit a request to the Message Batches API, you supply a custom_id string alongside each individual request object. The API processes your batch asynchronously — results are not guaranteed to arrive in submission order — so custom_id is the only reliable mechanism for matching each result back to the job that produced it.

A custom_id must be unique within the batch but is completely opaque to the API. It never leaves the request/result pair: Anthropic stores it, attaches it to the corresponding result object, and returns it unchanged. You own the semantics — common choices include database primary keys, file paths, task IDs, commit hashes, or any stable identifier from your upstream data.

How matching works in practice

When you poll for results, each result object carries the same custom_id you sent:

{
  "custom_id": "review-pr-4821",
  "result": {
    "type": "succeeded",
    "message": { ... }
  }
}

Your processing loop iterates over results and dispatches each one using custom_id as the lookup key. Without this field there would be no safe way to attribute a response when batch sizes run into the thousands and partial failures shuffle the order further.

Failure cases and `custom_id`

If an individual request errors (e.g., a request-level validation failure or a per-item stop_reason of refusal), the result object still carries the original custom_id and a result.type of errored. Always inspect result.type before reading result.message; a missing or wrong custom_id lookup is a common source of silent bugs in batch pipelines.

Design guidelines

• Keep custom_id values short and deterministic — avoid UUIDs unless you already have them. A slug like doc-42-chunk-7 is easier to debug in logs than a random UUID.
• Build your result-processing loop to handle results arriving in arbitrary order from the start; never assume index position.
• If you are retrying a batch, generate a new custom_id to avoid confusion with previous run artifacts, or include a run-number suffix.

See Batch Processing Strategy & API Selection for a broader look at when to prefer the Batches API over synchronous calls and how to structure high-volume pipelines.

Expect scenario questions: a batch of 500 code-review tasks is submitted; results arrive in a different order; which field lets the system route each result to the correct PR? The answer is custom_id. You may also see questions distinguishing custom_id (client-supplied, correlation only) from the id field the API generates for the overall batch object, or asking what result.type values indicate success vs failure.