Skip to main content
Reducto offers two processing modes: synchronous and asynchronous. The SDK provides run() and run_job() methods that map to different API endpoints:
SDK MethodAPI EndpointReturns
client.parse.run()POST /parseFull result (blocks until complete)
client.parse.run_job()POST /parse_asyncJob ID (returns immediately)
The same pattern applies to all endpoints: /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()

MethodBehaviorBest for
run()Calls sync endpoint, blocks until completeInteractive applications, smaller documents
run_job()Calls async endpoint, returns job IDLarge documents, high volume, background processing
Both methods produce the same results. The difference is whether you wait synchronously or retrieve results later.

​
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)
The 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
The 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:
StatusMeaning
PendingJob is queued, waiting for a worker
InProgressA worker is actively processing the document
CompletingProcessing finished, results being saved
CompletedResults are ready to retrieve
FailedProcessing failed (check error message)
Jobs typically spend most of their time in 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)
Polling is straightforward but requires keeping a process running. For production systems processing many documents, webhooks are more efficient.

​
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
    }
)
Priority jobs are processed before non-priority async jobs but may still queue behind synchronous requests.

​
Async endpoints

Every Reducto endpoint has a corresponding async variant:
Sync EndpointAsync EndpointSDK Method
POST /parsePOST /parse_asyncclient.parse.run_job()
POST /extractPOST /extract_asyncclient.extract.run_job()
POST /splitPOST /split_asyncclient.split.run_job()
POST /pipelinePOST /pipeline_asyncclient.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"
)

​
Using metadata

Include metadata with your job submission to help identify and route results: 
submission = client.parse.run_job(
    input="https://example.com/document.pdf",
    async_={
        "metadata": {
            "user_id": "user_123",
            "document_type": "invoice",
            "batch_id": "batch_456"
        }
    }
)
The metadata is included in webhook notifications, making it easy to match results back to your application context without maintaining a separate mapping.

​
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.
Default behavior: Job results are retained for 12 hours. After this window, you’ll need to reprocess the document. For longer retention: Enable 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.
Best practice: Always store results in your own database when you receive them via polling or webhook, rather than relying on Reducto’s retention.

​
API Reference

See the full API documentation for async endpoints:

Svix Webhooks

Get notified when jobs complete instead of polling.

Batch Processing

Process many documents in parallel with run().

Chaining Endpoints

Reuse parsed documents across multiple calls.

Pipeline Basics

Bundle workflows into a single API call.