Reducto offers two processing modes: synchronous and asynchronous. The SDK provides run() and run_job() methods that map to different API endpoints:
| SDK Method | API Endpoint | Returns |
|---|
client.parse.run() | POST /parse | Full result (blocks until complete) |
client.parse.run_job() | POST /parse_async | Job ID (returns immediately) |
/extract vs /extract_async, /split vs /split_async, and /pipeline vs /pipeline_async.
The Go SDK is currently in alpha and has limited async support. Go users should use the REST API directly for async operations. See the cURL examples below.
run() vs run_job()
| Method | Behavior | Best for |
|---|
run() | Calls sync endpoint, blocks until complete | Interactive applications, smaller documents |
run_job() | Calls async endpoint, returns job ID | Large documents, high volume, background processing |
Synchronous: run()
from reducto import Reducto
client = Reducto()
# Blocks until parsing completes (may take seconds to minutes)
result = client.parse.run(input="https://example.com/document.pdf")
print(result.result.chunks)
run() method handles the job lifecycle internally. If the document takes too long, the request may time out. For documents over 50 pages or complex processing, consider using run_job() instead.
Asynchronous: run_job()
from reducto import Reducto
client = Reducto()
# Returns immediately with job ID
submission = client.parse.run_job(input="https://example.com/document.pdf")
print(f"Job submitted: {submission.job_id}")
# Retrieve results later via polling or webhook
run_job() method has no limit on concurrent submissions. You can queue thousands of documents and process them in parallel without managing connections or timeouts.
Job lifecycle
When you submit a job via the async endpoint, it moves through these states:
| Status | Meaning |
|---|
Pending | Job is queued, waiting for a worker |
InProgress | A worker is actively processing the document |
Completing | Processing finished, results being saved |
Completed | Results are ready to retrieve |
Failed | Processing failed (check error message) |
Pending (waiting for capacity) or InProgress (actual processing).
Polling for results
The simplest way to get results from an async job is to poll the job status:
import time
from reducto import Reducto
client = Reducto()
# Submit job
submission = client.parse.run_job(input="https://example.com/document.pdf")
# Poll until complete
while True:
job = client.job.get(submission.job_id)
if job.status == "Completed":
print("Success:", job.result)
break
elif job.status == "Failed":
print("Failed:", job.error)
break
time.sleep(2)
Priority processing
By default, synchronous (run()) jobs are prioritized over asynchronous (run_job()) jobs. This ensures interactive requests get fast responses while background jobs process when capacity is available.
You can request priority processing for async jobs if your account has priority budget available:
submission = client.parse.run_job(
input="urgent-document.pdf",
async_={
"priority": True
}
)
Async endpoints
Every Reducto endpoint has a corresponding async variant:
| Sync Endpoint | Async Endpoint | SDK Method |
|---|
POST /parse | POST /parse_async | client.parse.run_job() |
POST /extract | POST /extract_async | client.extract.run_job() |
POST /split | POST /split_async | client.split.run_job() |
POST /pipeline | POST /pipeline_async | client.pipeline.run_job() |
# Parse
parse_job = client.parse.run_job(input="https://example.com/document.pdf")
# Extract
extract_job = client.extract.run_job(
input="https://example.com/document.pdf",
instructions={"schema": your_schema}
)
# Split
split_job = client.split.run_job(
input="https://example.com/document.pdf",
split_description=[{"name": "Section A", "description": "..."}]
)
# Pipeline
pipeline_job = client.pipeline.run_job(
input="https://example.com/document.pdf",
pipeline_id="your_pipeline_id"
)
submission = client.parse.run_job(
input="https://example.com/document.pdf",
async_={
"metadata": {
"user_id": "user_123",
"document_type": "invoice",
"batch_id": "batch_456"
}
}
)
When to use async
Use run() when:
- Processing single documents interactively
- Document size is small (under 20 pages)
- You need results immediately in the same request
- Testing and development
Use run_job() / async endpoints when:
- Processing many documents in parallel
- Documents are large or complex
- You want fire-and-forget with webhook notification
- Building batch processing pipelines
- Processing in background workers
Job Retention
Jobs are deleted after 12 hours. This is part of Reducto’s zero data retention (ZDR) policy. If you query a job ID from more than 12 hours ago, you’ll receive a “Job not found” error.
persist_results to keep results indefinitely:
result = client.parse.run(
input="document.pdf",
settings={"persist_results": True}
)
# This job's results will be stored indefinitely
persist_results requires opting in to Reducto Studio. Contact support to enable this feature for your organization.
API Reference
See the full API documentation for async endpoints:
