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.

​
List and filter jobs

List jobs visible to your API key with GET /api/v2/jobs. Use operation=parse or operation=extract to filter by the recorded operation. A Parse request with a schema creates an extraction phase in the same job, which is listed with operation=extract. A blocking Extract from a Parse ID can return a result without creating a listable job. The list omits jobs whose results have expired.
The response contains jobs, next_cursor, and total_count. The count covers all matching jobs across pages. total_count is null when the server cannot count matching jobs. Older servers might omit the field. Pass next_cursor as cursor to retrieve the next page. Each listed job and retrieved job includes request_source. The value is transform-ui for jobs created in the Transform web app or transform-api for direct API calls. The value is null when Transform does not report the origin. See the List jobs reference for all filters and response fields.

​
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.