How to OCR Scanned PDFs to Text with an API

A scanned PDF has no text to copy or search, only page images. Getting text out of it means rendering each page, running OCR in the right language and stitching the result back together, and doing that reliably for thousands of files is where most of the work goes.

Running Tesseract yourself is free but needs a renderer, language packs, a queue and servers. Desktop tools work one file at a time. The PDF OCR actor wraps Tesseract 5 behind an API, reads pages that already have a text layer without OCR, and reports a confidence score for every OCR'd page.

This guide sets up a page-level OCR run, checks the quality of the result in Python, rebuilds full documents from page rows, and shows when to use the mixed-format OCR to Text actor instead.

Step by step

1. Gather the PDF links and any password

   Each PDF must be reachable by URL. Files up to 100 MB and up to 2,000 pages are supported. If some PDFs are password-protected and you are entitled to open them, put the password in password; it applies to every PDF in that run, so group files that share a password.

2. Choose languages and PDF mode

   Pick only the languages your documents use, up to 4, using Tesseract codes such as eng, deu, fra or chi_sim. Fewer languages is faster and more accurate. Keep pdfMode on auto so pages that already contain text are read directly at the cheaper price; switch to ocr-all only for PDFs whose hidden text layer is known to be garbage.

   {
     "urls": [
       "https://raw.githubusercontent.com/ocrmypdf/OCRmyPDF/main/tests/resources/linn.pdf"
     ],
     "languages": ["eng", "deu"],
     "pdfMode": "auto",
     "outputMode": "pages",
     "dpi": 300,
     "maxPagesPerPdf": 500,
     "minWordConfidence": 40
   }

3. Tune for your document type

   Leave dpi at 300 for normal scans; 200 is faster for large print. pageSegmentation defaults to auto; use single-column for uniform book-like text and sparse for forms with scattered fields. Setting minWordConfidence to around 40-60 removes most noise from stains and stamps. Raise maxPagesPerPdf above the default 200 if your documents are longer, or they will be marked truncated.

4. Flag low-confidence pages for review

   With outputMode set to pages, every row is one page with page, confidence, wordCount and text. Clean printed scans usually score above 95; handwriting, stamps and low-resolution scans score lower. Sort by confidence and send the weakest pages to a human.

   import os
   from apify_client import ApifyClient
   
   client = ApifyClient(os.environ["APIFY_TOKEN"])
   run = client.actor("actor-forge/pdf-ocr").call(run_input={
       "urls": ["https://raw.githubusercontent.com/ocrmypdf/OCRmyPDF/main/tests/resources/linn.pdf"],
       "languages": ["eng"],
       "outputMode": "pages",
   })
   rows = list(client.dataset(run["defaultDatasetId"]).iterate_items())
   
   THRESHOLD = 80
   for r in rows:
       if r.get("error"):
           print("ERROR", r.get("url"), r["error"])
           continue
       conf = r.get("confidence")  # empty for text-layer pages
       if conf is not None and conf < THRESHOLD:
           print(f"REVIEW {r['url']} page {r.get('page')}: confidence {conf}")

5. Rebuild one text file per PDF

   Page rows are ideal for page-level search, but you often also want one text file per document. Group rows by URL, sort by page number and join them. Alternatively set outputMode to document to get one row per PDF directly.

   from collections import defaultdict
   from pathlib import Path
   import hashlib
   
   pages = defaultdict(list)
   for r in rows:
       if r.get("text"):
           pages[r["url"]].append((r.get("page") or 0, r["text"]))
   
   out = Path("ocr_text")
   out.mkdir(exist_ok=True)
   for url, items in pages.items():
       name = hashlib.sha1(url.encode()).hexdigest()[:12] + ".txt"
       text = "\n\n\f\n\n".join(t for _, t in sorted(items))  # form feed between pages
       (out / name).write_text(text, encoding="utf-8")
       print(name, "<-", url)

6. Use OCR to Text for mixed PDFs and images

   If the same pipeline also receives photos, TIFF faxes or screenshots, send everything to OCR to Text instead. It takes the same inputs, accepts PDF and image formats in one urls list, and defaults to one row per file. Pricing is identical.

7. Cap the cost of big batches

   Set a maximum total charge on the run. Processing stops cleanly at the cap and no page is charged twice, so an unexpectedly long archive cannot overrun your budget. maxFiles (up to 10,000) gives a second limit on the number of files per run.

Sample input

{
  "urls": [
    "https://raw.githubusercontent.com/ocrmypdf/OCRmyPDF/main/tests/resources/linn.pdf",
    "https://arxiv.org/pdf/1706.03762"
  ],
  "languages": [
    "eng"
  ],
  "pdfMode": "auto",
  "outputMode": "pages",
  "maxPagesPerPdf": 200
}

Sample output

The sample shows a scanned PDF that needed OCR and a digital PDF read entirely from its text layer, with the page counts for each method.

Run it from code

cURL

curl -X POST "https://api.apify.com/v2/acts/actor-forge~pdf-ocr/run-sync-get-dataset-items" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://raw.githubusercontent.com/ocrmypdf/OCRmyPDF/main/tests/resources/linn.pdf", "https://arxiv.org/pdf/1706.03762"], "languages": ["eng"], "pdfMode": "auto", "outputMode": "pages", "maxPagesPerPdf": 200}'

JavaScript (Node.js)

// Node.js 18+ (built-in fetch). Set APIFY_TOKEN in your environment.
const input = {
  "urls": [
    "https://raw.githubusercontent.com/ocrmypdf/OCRmyPDF/main/tests/resources/linn.pdf",
    "https://arxiv.org/pdf/1706.03762"
  ],
  "languages": [
    "eng"
  ],
  "pdfMode": "auto",
  "outputMode": "pages",
  "maxPagesPerPdf": 200
};

const res = await fetch(
  "https://api.apify.com/v2/acts/actor-forge~pdf-ocr/run-sync-get-dataset-items",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.APIFY_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(input),
  }
);
const items = await res.json();
console.log(items.length, items[0]);

Python

# pip install apify-client   (set APIFY_TOKEN in your environment)
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run_input = {
    "urls": [
        "https://raw.githubusercontent.com/ocrmypdf/OCRmyPDF/main/tests/resources/linn.pdf",
        "https://arxiv.org/pdf/1706.03762"
    ],
    "languages": [
        "eng"
    ],
    "pdfMode": "auto",
    "outputMode": "pages",
    "maxPagesPerPdf": 200
}

run = client.actor("actor-forge/pdf-ocr").call(run_input=run_input)
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

The run-sync-get-dataset-items endpoint waits for the run (up to 5 minutes) and returns the dataset rows directly. For longer runs, start the run asynchronously and read the dataset when it finishes, as the Python example does. Replace APIFY_TOKEN with your own token from the Apify console.

What it costs

An archive of 400 scanned PDFs averaging 12 pages is 4,800 OCR pages, so 4,800 x $0.003 = $14.40. A 200-page PDF where only 20 pages are scanned costs 20 x $0.003 + 180 x $0.0003 = $0.06 + $0.054 = $0.114.

Tips and pitfalls

• Rotate pages that are sideways or upside down before submitting; 90 and 180 degree rotations are not corrected automatically.
• Tables come out as lines of text, not structured tables. Plan a separate extraction step if you need table cells.
• Modern Greek is not available, and handwriting comes out poorly. Use the confidence score to find pages that need a human.
• Links that return a web page instead of a file are reported and not charged; check for login walls on document links.

FAQ

Actors used in this guide

Related guides

All guides