OpenAI Batch custom_id Correlation Needs a Manifest
OpenAI Batch custom_id correlation works when every JSONL request receives a unique, opaque identifier tied to an immutable local manifest. Output order can differ from input order, successful results and failures land in separate files, and artifacts expire. This guide defines the manifest, reconciliation states, duplicate checks, and audit evidence needed for production batch processing.

An OpenAI Batch output file can return line 8 before line 2. Successful requests appear in the output file, while failed requests appear in a separate error file. The stable join is custom_id, an identifier supplied on every input line. Production correlation therefore begins with a local manifest created before the JSONL file leaves your environment.
I want that manifest to answer one operational question with a single lookup: which source record and approved request belong to cust_01J..., and which provider result and downstream write correspond to them.
TL;DR
- Generate a unique, opaque custom_id for every JSONL line and bind it to one immutable manifest row before upload.
- Join output and error lines by custom_id because OpenAI states that output order may differ from input order.
- Reconcile every manifest row into one terminal state, including missing, duplicate, expired, cancelled, and malformed cases.
- Preserve batch, file, provider request, and policy decision IDs while keeping source secrets and raw credentials outside the identifier.
custom_id is the result join key
OpenAI's Batch API guide requires each request line to include a unique custom_id. The same guide states that output line order may differ from input order and directs clients to use custom_id for mapping each result back to its request.
That behavior rules out array index and output position as durable correlation methods. It also rules out line number after transformation. A JSONL formatter may reorder work. Processing completes asynchronously. Separate result files divide success and failure records. A stable application-generated key survives all three changes.
Generate the identifier before serialization and keep it opaque within a documented length bound. A sortable random identifier works well because it carries uniqueness without exposing a customer email, case number, diagnosis code, or internal database primary key. Store human-readable context in the manifest rather than encoding it into the identifier.
Uniqueness belongs to the input file at minimum because OpenAI validates each batch input. I prefer a wider namespace across the deployment. A globally unique key simplifies incident searches when two batches are downloaded into the same evidence store.
The AI audit log schema provides a field pattern for correlation IDs. A batch manifest adds source and reconciliation state around that pattern.
The manifest freezes request intent
Create one manifest row per planned JSONL line. Write it before file upload and make later changes append-only. The row should contain:
custom_id, tenant scope, source-system record ID, and approved purpose.- A canonical request fingerprint plus the model and endpoint, with selected parameters.
- Input file version, line number for diagnostics, batch generation time, and submitting workload identity.
- Data classification, policy version, retention class, and downstream destination.
- Reconciliation state, output fingerprint, provider request ID, and final write ID when those values arrive.
The fingerprint detects accidental reuse. If a build process emits the same custom_id with changed prompt text or model parameters, fail before upload. Keep canonicalization narrow and versioned so two workers calculate the same digest.
My blunt view is that a spreadsheet mapping line numbers to customer rows is an incident waiting for someone to sort one column. The manifest deserves database constraints and a release test.
Place a printed JSONL sample beside the manifest during review. Draw a pencil line from cust_01J8R... to its source row and then to the expected output slot. That physical trace exposes a missing join field faster than a slide labelled "observability."
Batch, file, and request IDs serve different jobs
The custom_id belongs to an individual request line. OpenAI also assigns an input file ID, a batch ID, output and error file IDs, an internal batch-request ID, and a provider request ID inside successful result records. Preserve each value under its own field name.
The Batch API reference defines the Batch object, including status, request counts, timestamps, output_file_id, and error_file_id. These identifiers describe artifacts and processing state. They should remain alongside custom_id rather than replacing it.
Build the relationship as one batch to one input file, then one batch to many manifest rows. Each manifest row can receive one success line or one error line during normal reconciliation. The provider request ID supports OpenAI support investigation for that individual execution. The output file ID proves which artifact supplied the downloaded record.
Keep application correlation separate from provider identity. A source record can enter a later correction batch under a fresh custom_id. Link the two manifest rows with an application-level supersession field. Reusing the old identifier would blur two distinct submissions and weaken the audit history.
Reconciliation reads both result files
OpenAI documents one response line in the output JSONL for every successful request line. Failed requests have error information in the file identified by error_file_id. A reconciler must read both artifacts before deciding that a manifest row is missing.
The reconciler should parse each downloaded line independently. Validate its shape and extract custom_id. Then perform an exact lookup in the expected manifest namespace. Then apply these checks:
- Unknown identifier: quarantine the line and preserve its source file ID.
- Duplicate identifier in one artifact: mark the batch inconsistent and retain both line fingerprints.
- Identifier present in output and error files: block downstream writes until an operator resolves the conflict.
- Missing identifier: reject the line as malformed.
- Expected manifest row absent from both files: assign a pending investigation state until batch status and request counts have been examined.
Avoid a "last line wins" map. That implementation hides duplicates by overwriting the first value. Count occurrences before building the final join.
The AI audit log chain-of-custody guide applies to the downloaded artifacts. Hash the complete files on receipt and record retrieval time with the authenticated workload identity. Then retain parsed row fingerprints beside the original artifact reference.
Terminal batch state still needs row-level accounting
A completed batch is an artifact-level state. Row accounting remains a separate task. Compare the number of manifest rows with the total accepted success and error lines, then inspect OpenAI's request counts. Differences should produce an explicit reconciliation hold.
Cancellation and expiry require the same discipline. OpenAI says a cancelling batch can keep in-flight requests running before reaching cancelled. The guide also explains that output and error files expire 30 days after creation by default, with a configurable range on batch creation. Download and verify artifacts inside a scheduled retention window.
Use row states such as planned, submitted, succeeded, failed, missing, duplicate, quarantined, and written. Reserve written for the downstream transaction. A successful provider response can still fail schema validation or target-record authorization. The manifest should preserve both outcomes as separate facts.
For downstream updates, place custom_id under a unique constraint with the target action. Reprocessing the downloaded output can then return the prior write result. The OpenAI Agents SDK audit logs guide makes a similar distinction between provider execution evidence and application-owned identity and custody.
Release fixtures should scramble and split results
Build a small fixture with at least six manifest rows and a controllable parser. Put successful lines in a different order and send two failures to the error artifact. Duplicate one identifier, introduce one unknown identifier, and omit one expected row. The reconciler should produce six named row outcomes plus quarantined evidence for the extras.
Add these acceptance cases:
- Two input lines attempt to use the same
custom_idbefore upload. - One identifier is reused with a changed request fingerprint.
- A result line has a success status while its body schema is malformed.
- The output download ends halfway through a JSONL line and resumes under a new artifact receipt.
- A cancelled batch supplies partial output and error files.
- Artifact retrieval begins after the configured expiry time.
- Two reconciler workers process the same file concurrently.
- A downstream writer crashes after commit and before manifest acknowledgment.
The final evidence packet should include manifest version, input file hash, batch ID, result file hashes, occurrence counts, row-state totals, quarantined line references, and downstream commit IDs. The AI agent observability guide covers runtime traces. This packet serves a narrower accounting purpose: every submitted row reaches one explainable disposition.
DeepInspect
DeepInspect can evaluate authenticated user or agent HTTP model requests deliberately routed through its proxy. For a routed batch upload or creation request, it can apply identity-aware policy to the supplied context and produce a decision record tied to the route and destination, with the policy version and classification.
The batch client remains owner of custom_id generation, JSONL validity, manifest integrity, file upload, batch polling, artifact download, row reconciliation, and downstream commits. OpenAI owns the documented Batch API processing and artifacts. Direct calls that bypass the routed path remain outside DeepInspect visibility.
Carry a DeepInspect decision ID into the local submission record when the route supports approved metadata, or join it through the client attempt ledger. Keep the Batch manifest as the system of record for row-level correlation.
Book a demo today.