Docling-Serve request timeout

[enx-github]

Hello,
I’m using Docling to extract from .pdf and .docx.
Now I want to switch the extraction part to use docling-serve.

That means I need to call docling-serve from my client code, and I’m planning to use the httpx library for that.

My confusion:

• Some files are extracted within 1 minute,
• while others take 2–3 hours.

So, my question is: How do I use httpx so it will reliably wait for the docling-serve response, even for long extractions?

[dosubot[bot]]

To handle long-running extractions with docling-serve, you should use the asynchronous endpoints (/v1/convert/source/async or /v1/convert/file/async). The synchronous endpoints have a server-side timeout (default 2 minutes), so increasing the httpx timeout won't help for jobs that take hours—they'll always fail with a timeout from the server if they run too long (docs/configuration.md).

The async workflow is: submit your job via the async endpoint, get a task_id in the response, then poll /v1/status/poll/{task_id} or subscribe to /v1/status/ws/{task_id} (websocket) until the job is done, and finally fetch the result. This pattern is robust for multi-hour jobs (docs/usage.md).

Example with httpx (polling):

import httpx
import time

# Submit the async job
with httpx.Client() as client:
    response = client.post("http://localhost:5001/v1/convert/file/async", files=files, data=parameters)
    task = response.json()

# Poll for status
while task["task_status"] not in ("success", "failure"):
    response = httpx.get(f"http://localhost:5001/v1/status/poll/{task['task_id']}")
    task = response.json()
    time.sleep(5)

# Fetch result when done
if task["task_status"] == "success":
    result = httpx.get(f"http://localhost:5001/v1/result/{task['task_id']}")
    # handle result

You can set the httpx timeout as high as you want, but for async jobs, each poll is a short request, so the default is usually fine. The server-side max_document_timeout (default 7 days) controls the maximum allowed extraction time for async jobs (settings.py).

Summary: use async endpoints and poll or subscribe for status; don't rely on httpx timeouts for long-running synchronous requests.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[enx-github]

Thank you for quick reply. I will try this solution.

[enx-github]

I am getting "timed out" error using this code

I am using below command to run container
docker run --name docling-serve -e DOCLING_SERVE_ENABLE_UI=true -p 5001:5001 ghcr.io/docling-project/docling-serve-cu128