Skip to main content
Parse and Extract can return the result in the original request or let you retrieve it later. The optional Prefer header controls how long that original request waits.

​
Choose how long to wait

The server can cap the requested wait. Read Preference-Applied: wait=N for the value it honored. Omitting the header sets no Prefer wait deadline; client and network timeouts can still interrupt the request. Processing failures return errors rather than successful results.

​
Request asynchronous processing

Set your key using the API key setup and put document.pdf in your working directory.
An illustrative HTTP 202 body is:

​
Retrieve a result after HTTP 202

The API can return a relative path in the Location header, such as /api/v2/jobs/<job-id>, or an absolute URL. Some responses include the same value in poll_url. Preserve the returned value and resolve a relative path against the Transform API host. Parse and Extract jobs use this retrieval endpoint.
This command retrieves once. Repeat it after a delay while processing is pending. For complete polling loops, see the Python and TypeScript examples. Poll the existing job rather than resubmitting the document. Retrieval returns a wrapper object with status, error, and result. Read Parse content from result.markdown or result.elements; read Extract values from result.extracted_data[i].data. If the job exists but its stored result is no longer available, retrieval returns HTTP 410 with result_expired. Re-run the original request to produce a new result.

​
Interpret status

Warnings describe a result that succeeded with qualifications. They are not an error response or a confidence score.

​
Inspect warnings

completed_with_warnings means the job returned a result, but processing reported qualifications. It is different from failed: a failed job has no completed result to use. Each warning has a stable code for application logic and a human-readable message:
Read the result and verify the fields your application needs. If a warning means required content is missing or unusable for your workflow, retain the job ID and warning details, then follow the recovery guidance. Otherwise, you can use the completed result.

​
Stream Parse progress

For a Parse retrieval URL, request server-sent events:
The stream ends in a result event containing a job result or an error event. The contract does not promise estimated stage durations.

​
Cancel a Parse job

Set JOB_ID to the Parse job ID:
Cancellation returns the current job snapshot. Continue checking status; a cancellation request is not confirmation that work stopped. Jobs that have completed, failed, or been cancelled remain unchanged. Before resubmitting, wait for the original job to reach a final status and check for a result. Resubmitting while it is still running can process the document twice. See job retrieval, cancellation, and expiry recovery.