How Processing Works

Document processing is asynchronous. Upload and reprocessing requests return after a run is accepted; processing continues independently.

Documents, runs, and results

Document AI uses three related resources:

A document represents the uploaded file and its current state.
A run represents one processing attempt with a fixed configuration snapshot.
A result contains structured output from a completed run. Split processing can produce multiple results from one document.

Every new processing attempt creates a new run. Prior runs and results remain available for comparison and audit.

Configuration snapshot

When a run is created, its selected processing configuration is captured as a complete snapshot. Later edits to a saved configuration do not change an existing run.

Learn how to select the appropriate settings in Choosing a Configuration.

Status lifecycle

Status	Meaning	What to do
`pending`	The run was accepted and is waiting to start.	Continue polling or wait for an event.
`processing`	Work is in progress.	Display progress and continue waiting.
`completed`	Processing finished successfully.	Retrieve and use the results.
`failed`	Processing could not complete.	Inspect `error`, correct the input or configuration, then create a new run if appropriate.
`skipped`	Processing was not applicable to the stored file.	Review the skip reason and file eligibility.
`oversized`	The file exceeds a processing limit but may still be stored.	Review the reported reason and current file-type limits.

Treat completed, failed, skipped, and oversized as terminal for that run.

Monitor a run

Use GET /document-store/runs/{id} to retrieve a run.

The response includes:

status
current_step and current_step_message , when available
error , when processing fails
created_at , started_at , and completed_at
The configuration snapshot used for that run
Result summaries when processing completes

Review processing activity

Use GET /document-store/activity for customer-visible progress and troubleshooting entries.

Filter by document_id or run_id. Entries include the processing step, status, message, and creation time. Results default to 25 per page and support up to 100.

Polling guidance

Start with a short delay, then increase the interval while the run remains non-terminal.
Stop polling when the run reaches a terminal status.
Prefer document lifecycle events when your integration already receives Shipwell webhooks.
Do not start a duplicate run only because a run remains pending or processing longer than expected.

When a run completes, continue to Reading Results. To start another attempt or review history, see Runs and Reprocessing.