Python SDK

The Python SDK lets you parse documents and extract fields without building HTTP requests by hand.

Install the package

Install from PyPI. You need Python 3.12 or newer, uv, version 0.18.18 or newer of the SDK, and a Transform API key. The shell examples use zsh. Run these commands from your project directory:

uv venv .venv
uv pip install --python .venv/bin/python "unstructured-transform-client>=0.18.18"

Set your API key

Export your key in the zsh session where you will run the script. Replace the placeholder with your key:

export UNSTRUCTURED_API_KEY="your-api-key"

Keep your key out of source control and shared scripts.

Parse a document synchronously

A synchronous call waits for processing to finish and returns the result in the same request. Multi-page documents can take about a minute or longer. That wait is expected. Save the code as parse.py and put document.pdf in the same project directory. To try the example without your own file, download the ACME Corp Annual Report sample PDF and save it as document.pdf in your project directory.

from unstructured_transform_client import TransformClient

with TransformClient() as client:
    result = client.parse.run(input="document.pdf")
    print(result)

Run the script from that directory, in the same shell where you exported your key:

.venv/bin/python parse.py

The call prints the returned response. Look for the parsed text in markdown. Markdown is the default output; no output or profile options are required. If you omit api_key, the client reads UNSTRUCTURED_API_KEY from the environment. The client defaults to https://transform.unstructured.io. Pass server_url only when you target a different deployment. If you omit wait_seconds, the call waits for the result in the original request. Client and network timeouts can still interrupt the request.

Extract fields next

To extract structured fields, follow Chain Parse and Extract. That guide defines a schema and reuses a completed Parse ID.

Handle long-running requests

Asynchronous processing lets the server continue working after the submission returns. You retrieve the result in a later request. This is separate from Python’s async/await: the client methods below are ordinary synchronous Python calls.

Parse or Extract option	Behavior
Omit `wait_seconds`	Wait for the result in the original request.
`wait_seconds=0`	Return a pending job handle without waiting for processing to finish.
`wait_seconds=N`	Wait up to the duration honored by the server, then return the result or a pending handle.

The SDK sends wait_seconds as the HTTP Prefer: wait=N header. The server can cap the requested duration. See wait behavior and request progress for HTTP 200, HTTP 202, and timeout handling.

Retrieve an asynchronous Parse

Set your API key as shown above and save your document as document.pdf. Save this complete example as parse_async.py and run .venv/bin/python parse_async.py from the project directory. It submits the document and polls until processing finishes:

import time
from unstructured_transform_client import TransformClient

with TransformClient() as client:
    # Submit once and retain the job ID for retrieval.
    accepted = client.parse.run(input="document.pdf", wait_seconds=0)
    print("Parse job ID:", accepted.id)

    # Poll the same job until processing reaches a final status.
    job = client.jobs.get(accepted.id)
    while job.status in ("queued", "processing"):
        time.sleep(2)
        job = client.jobs.get(accepted.id)

    # Retrieval wraps the parsed document under result.
    if job.status in ("completed", "completed_with_warnings"):
        print(job.result)
    elif job.status == "failed":
        raise RuntimeError(job.error)
    else:
        print("Parse stopped:", job.status)

The two-second delay is an example polling interval, not a server requirement. Stop the script to stop polling; this does not cancel the server job. Keep the job ID to resume retrieval. If you request output="elements", pass that option on retrieval too and read job.result.elements after success.

Poll an accepted extraction

Use the SDK version installed above. Replace your-completed-parse-id with a completed Parse ID. The example schema requests an invoice number; adapt it using the schema guide.

import time

from unstructured_transform_client import TransformClient

with TransformClient() as client:
    parse_id = "your-completed-parse-id"
    schema = {"type": "object", "properties": {"invoice_number": {"type": "string"}}, "required": ["invoice_number"], "additionalProperties": False}
    accepted = client.extract.run(parse_id=parse_id, schema=schema, wait_seconds=0)
    deadline = time.monotonic() + 300
    job = client.jobs.get(accepted.id)
    while job.status in ("queued", "processing"):
        if time.monotonic() >= deadline:
            raise TimeoutError(f"extraction {accepted.id} is still {job.status}")
        time.sleep(2)
        job = client.jobs.get(accepted.id)
    if job.status in ("completed", "completed_with_warnings"):
        print(job.result.extracted_data)
    elif job.status == "failed":
        raise RuntimeError(job.error)
    else:
        print("Extraction stopped:", job.status)

The two-second delay is an example polling interval, not a server requirement. Keep the job ID to resume retrieval. Check the final status before using job.result.extracted_data.

Iterate over jobs

from unstructured_transform_client import TransformClient

with TransformClient() as client:
    for job in client.jobs.iterate(status="completed"):
        print(job.id, job.status)

iterate follows cursors and yields individual jobs. Use jobs.list() when you need one page at a time.

Configure retries

Add retries when creating your client:

from unstructured_transform_client import RetryConfig, TransformClient

client = TransformClient(
    retries=RetryConfig(max_attempts=5, max_elapsed_seconds=20),
)

Pass retries=None to disable retries. The client uses backoff for eligible transient failures. A submission that might already have created a job is not retried after a read timeout or server response, to avoid duplicate jobs. See Chain Parse and Extract for a complete sequence that passes the Parse ID into Extract.

Integrate

API Reference

API endpoints

Install the package

Set your API key

Parse a document synchronously

Extract fields next

Handle long-running requests

Retrieve an asynchronous Parse

Poll an accepted extraction

Iterate over jobs

Configure retries

​Install the package

​Set your API key

​Parse a document synchronously

​Extract fields next

​Handle long-running requests

​Retrieve an asynchronous Parse

​Poll an accepted extraction

​Iterate over jobs

​Configure retries

Install the package

Set your API key

Parse a document synchronously

Extract fields next

Handle long-running requests

Retrieve an asynchronous Parse

Poll an accepted extraction

Iterate over jobs

Configure retries