Batch Lifecycle

A batch tracks progress, and each document has its own outcome. A batch never succeeds or fails: it finishes as completed even when every document failed.

Batch Status

Status	Entered When	You Can
pending	The batch is created	Add, upload, and delete documents. Submit or cancel
processing	You submit	Poll. A repeat submit returns the batch
completed	Every document is succeeded, failed, or cancelled	Read results. Delete the batch
cancelled	You cancel, or the batch stays pending for 7 days	Delete the batch

Only a pending batch can be cancelled. expiresAt shows when an unsubmitted batch is cancelled automatically.

cancellationReason	Meaning
requested	You cancelled the batch
expired	The batch was not submitted before expiresAt

Document Status

Status	Meaning
awaiting_upload	Declared, but the file has not been uploaded. Submit is blocked
pending	Content received. Waiting for submit or for processing capacity
queued	Waiting to be processed
processing	Being processed
succeeded	Entities are available
failed	error.code gives the reason. See Errors
cancelled	The batch was cancelled before this document started

Submit needs at least one document and none in awaiting_upload.

Counts

counts updates while the batch is processing and is final once the batch is completed or cancelled. The status counts add up to total.

Field	Documents
total	All
awaitingUpload	awaiting_upload
pending	pending
queued	queued
processing	processing
succeeded	succeeded
failed	failed
cancelled	cancelled

Delete

Request	Allowed When	Effect
DELETE /v1/data-engine/batches/{batchId}	Batch is completed or cancelled	Deletes documents, entities, and files. Final counts are kept for usage reporting. A repeat delete returns 204
DELETE .../documents/{documentId}	Batch is pending	Deletes that document