OCR a 1000-Page Backlog with Batch

Clear a large scanning backlog asynchronously with 50% batch discount pricing.

Submit many OCR requests in one batch call
Poll the returned batch URL until completion
Download and merge all page results

Time to complete: ~20 minutes

Prerequisites

A SAGEA_API_KEY exported as an environment variable
Source files in PDF, PNG, JPG, TIFF, or WEBP format, each max 100MB, ideally 300 DPI
Python 3.9+ with the requests package installed
Set up document processing
ARVA OCR model card

Step 1: Submit the batch job

Post to /v1/batch with endpoint set to /v1/ocr/process for a 50% discount.

curl -X POST https://api.sagea.space/v1/batch \
  -H "Authorization: Bearer $SAGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"endpoint": "/v1/ocr/process", "requests": [{"model": "arva-ocr", "document_url": "https://example.com/scans/box-001.pdf", "output_format": "json"}, {"model": "arva-ocr", "document_url": "https://example.com/scans/box-002.pdf", "output_format": "json"}]}'

Single-document processing uses POST https://api.sagea.space/v1/ocr/process with model="arva-ocr" and document fields. Batch wraps the same endpoint.

Step 2: Poll until the batch completes

Poll the returned batch URL with backoff until status is complete.

BATCH_URL="https://api.sagea.space/v1/batch/batch_123"
curl -H "Authorization: Bearer $SAGEA_API_KEY" "$BATCH_URL"

Step 3: Download and merge results

Fetch each completed OCR result and combine the text and blocks.

import json
 
outputs = result.get("results", [])
merged_blocks = []
total_pages = 0
for item in outputs:
    total_pages += item.get("pages", 0)
    merged_blocks.extend(item.get("blocks", []))
 
print(f"total pages={total_pages} total blocks={len(merged_blocks)}")
with open("backlog-results.json", "w") as f:
    json.dump(outputs, f, indent=2)
 
with open("backlog-text.md", "w") as f:
    for item in outputs:
        f.write(item.get("text", "") + "\n\n")
print("wrote backlog-results.json and backlog-text.md")

Batch keeps the same JSON shape with text, pages, confidence, blocks, and model_used. Standard pages are $1.00 per 1000, complex $2.50 per 1000, less 50% off in batch.

Verify

Error	Cause	Fix
`401 Unauthorized`	Missing or invalid API key	Export a valid key as `SAGEA_API_KEY` and retry
`400 unsupported_format`	File type not in PDF, PNG, JPG, TIFF, WEBP	Convert source files to PDF or PNG and retry
`413 Payload Too Large`	A file in the batch is over 100MB	Split large PDFs and resubmit those items
`429 rate_limit_exceeded`	Too many requests at once	Lower submit rate and poll every 10 seconds or more