Documented steps

Authenticate with ADC or a service account token whose identity holds documentai.processors.processBatch (roles/documentai.apiUser or higher), plus storage read on the input bucket and write on the output bucket.
POST https://{LOCATION}-documentai.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/processors/{PROCESSOR_ID}:batchProcess, following the same regional hostname rule as the online path.
Set inputDocuments to either {"gcsDocuments":{"documents":[{"gcsUri":"gs://bucket/file.pdf","mimeType":"application/pdf"},...]}} for an explicit list, or {"gcsPrefix":{"gcsUriPrefix":"gs://bucket/directory/"}} to process a whole folder.
Set documentOutputConfig.gcsOutputConfig.gcsUri to the output directory — it must end with '/'. Optionally set fieldMask to restrict output fields and shardingConfig.{pagesPerShard,pagesOverlap} to control how large documents are split.
The call returns immediately with a long-running Operation name projects/{PROJECT_ID}/locations/{LOCATION}/operations/{OPERATION_ID}. There is no document body in the initial response.
Poll GET https://{LOCATION}-documentai.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/operations/{OPERATION_ID} until done=true. The metadata carries BatchProcessMetadata with per-file individualProcessStatuses, each including its own outputGcsDestination.
On completion, list objects under the output path, which follows the pattern gs://{OUTPUT_BUCKET}/{PREFIX}/{OPERATION_NUMBER}/{INPUT_FILE_NUMBER}/, and filter for application/json blobs.
Reassemble sharded results: download each shard's JSON, deserialize as a Document object, then merge shards belonging to the same source document in shard order, de-duplicating overlapping pages if pagesOverlap was configured. The Document AI Toolbox client library handles multi-shard merging automatically.
Config field reference: https://docs.cloud.google.com/document-ai/docs/reference/rest/v1/DocumentOutputConfig and flow example https://docs.cloud.google.com/document-ai/docs/samples/documentai-batch-process-document

Known gotchas

Batch input is capped at 1 GB per file, versus 40 MB online, and a single batchProcess call accepts at most 5,000 files. Larger corpora need multiple calls.
Per-document page limits still vary by processor type even on the async path — roughly 500 pages for general/Enterprise OCR processors, lower for several specialized parsers. Oversized documents need pre-splitting.
Concurrent batchProcess requests are quota-limited to roughly 5 per project by default. Beyond that the API returns RESOURCE_EXHAUSTED errors rather than silently queuing, so orchestration code must handle and back off.
Output is sharded per document once it exceeds the configured or default pagesPerShard. Reading only the first JSON file per input silently truncates large documents — always list and merge every shard under a document's output prefix.
An operation can report done=true while carrying an error status. Check metadata.individualProcessStatuses[].status per file rather than treating a completed operation as an all-succeeded operation.
Batch uses the same per-processor-type rates as online. Asynchronous processing does not reduce or waive the underlying page or document pricing tier.
The processor region must match the batchProcess hostname exactly, and input/output GCS buckets are expected to be in a compatible region to avoid cross-region latency or errors.
v1 is the stable surface for batchProcess. Verify that any DocumentOutputConfig or ShardingConfig field you depend on is documented under v1, not only under v1beta3, before relying on it in production.

Run an asynchronous Google Document AI batchProcess job over many GCS documents, poll the long-running operation, and reassemble sharded JSON output

Documented steps

Known gotchas

Related routes

Give your agent this knowledge — and 16,300+ more routes

Need this verified for your stack — or a route we don't have yet?