Evidence-First PDF Table Extractor

Extract tables from digital and scanned PDFs into full CSV and JSON exports while preserving where each table came from.

This Actor extracts PDF tables with review-oriented provenance, bounded outputs, explicit quality flags, and transparent pay-per-event pricing.

Why use it

Basic PDF text extractors flatten tables and discard evidence. This Actor produces:

• one dataset row per detected table;
• full CSV and JSON files in the default key-value store;
• source URL, final URL, PDF SHA-256, page number, and parser bounding box where available;
• OCR fallback for scanned regions using local CPU models;
• explicit structural quality flags and a documented heuristic score;
• bounded cells/exports plus spreadsheet-formula escaping in CSV;
• an error or no-table row for every document that does not produce tables.

No PDF content is sent to remote document-processing services. Docling and RapidOCR run inside the Actor container.

Input

Use pdfSources to upload PDFs or provide public PDF URLs. Defaults are deliberately bounded:

• 10 documents per run;
• 50 pages per PDF;
• 25 MB per PDF;
• 60-second absolute DNS/download deadline;
• 180-second hard conversion deadline;
• 3,072 MB isolated conversion-process RSS limit;
• 4,096 MB minimum Actor memory, with 768 MB reserved for the parent process;
• standard HTTP/HTTPS ports only;
• every connection pinned to a validated public IP; private, loopback, link-local, and metadata-network destinations blocked;
• HTTPS-to-HTTP redirect downgrades rejected.

ocrMode values:

• auto — inspect the PDF text layer, skip OCR when every processed page already has useful text, otherwise OCR bitmap regions; OCR-derived tables are beta and always flagged ocr_extraction_requires_review;
• always — force full-page OCR;
• never — disable OCR.

The requested and effective OCR modes are both reported in output rows.

tableMode: fast is the cost-controlled default. accurate can improve difficult grouped headers and merged cells, but it is materially slower. Neither mode is presented as universally superior; inspect quality flags and provenance for consequential use.

Output

Missing parser bounding boxes, coordinates, or coordinate origins are represented conservatively and flagged with missing_bbox_provenance; page-only or origin-less evidence is not presented as complete bounding-box provenance.

Every dataset row and JSON control record includes contractVersion: 1. Every dataset row also includes a one-based sourceIndex. Document and table IDs include the input occurrence, so repeated URLs or different URLs serving identical bytes cannot overwrite one another. Persisted sourceUrl and finalUrl values are intentionally redacted and are not raw retrievable URLs.

Dataset rows use recordType: table for extracted tables and recordType: document for no_tables, error, partial_write, or billing_error outcomes. Every row is validated against a field whitelist and a six-megabyte serialized-size ceiling before persistence.

Full exports are stored under:

table-<document-id>-001.csv
table-<document-id>-001.json
document-<document-id>.md
document-<document-id>-manifest.json
OUTPUT

The dataset includes only a bounded preview; use csvRecordKey or jsonRecordKey for the complete table. The document manifest is written last in the core persistence sequence. status: complete marks fully persisted core output; status: partial_write explicitly lists artifacts and dataset rows written before a late storage failure; status: billing_error means core output was complete but a configured PPE charge did not fully settle. Confirmed partial charges and the failed event are preserved in the finalized manifest and OUTPUT. JSON preserves bounded extracted values. CSV prefixes spreadsheet-formula-like strings with an apostrophe; outputFlags and spreadsheetEscapedCells report when that happened.

Quality score

qualityScore is a transparent structural heuristic, not model confidence or measured extraction accuracy. It penalizes empty/single-column tables, duplicate or blank headers, high blank-cell ratios, missing page provenance, and missing/incomplete bounding-box coordinates or coordinate origin. Run summaries therefore use structurallyUnflaggedTables and structurallyFlaggedTables, not “high quality.” Consumers should validate critical data against the cited PDF page and bounding box.

Pricing and PPE billing

This Actor uses pay per event + Apify platform usage. It preflights the user's maximum run budget before conversion and charges custom events only after document artifacts, dataset rows, and the core completion manifest are persisted.

Configured events:

• apify-actor-start — $0.00005 per allocated memory GB, charged automatically by Apify;
• document-processed — $0.010 per successfully persisted document;
• digital-page — $0.002 per selected page when OCR is skipped;
• ocr-page — $0.010 per selected page when OCR runs.

The synthetic apify-default-dataset-item event is deliberately disabled to avoid duplicate dataset-output charges.

Failed downloads, safety rejections, conversion failures, and OCR page-limit rejections are not charged by these custom events. Because platform usage is passed through, users can still incur small Apify platform-usage charges for failed runs even when no custom event is charged.

Limitations

• OCR is capped at three selected pages per document in this release. Set maxPagesPerDocument to 3 or less, split longer scans, or use ocrMode: never for digital PDFs.
• OCR table extraction is beta. Every OCR-derived table carries ocr_extraction_requires_review; clear image tables can still be missed, and detected cells can be misaligned.
• Complex nested headers, rotated tables, handwriting, and low-resolution scans may require review.
• OCR has been validated on English synthetic and public samples; broader language coverage is not established.
• Bounding-box coordinates use the parser's reported coordinate origin.
• URL DNS resolution has an absolute deadline; each connection uses the validated public IP directly while TLS verifies the original hostname. Redirects repeat validation and pinning.
• PDFium preflight and Docling conversion run in separate spawned process groups. The parent enforces hard wall-clock deadlines, samples process-tree RSS every 250 ms, and kills a group on an observed breach. RSS supervision is not a kernel/cgroup hard cap; a brief spike or container OOM can still precede the next sample.
• After Actor storage initialization, Python-level input, document, and fail-fast errors persist OUTPUT through an outer finally; Actor initialization failure, infrastructure termination, or container OOM can still prevent an application-level finalizer.
• Tables, provenance, previews, dataset rows, and exports are bounded; documents exceeding those bounds fail explicitly rather than silently truncating whole tables.
• The Actor extracts tables; it does not provide legal, financial, medical, or regulatory interpretation.
• This Actor is CPU-oriented and prioritizes inspectable output over speed.

Example input

{
  "pdfSources": ["https://arxiv.org/pdf/2206.01062"],
  "ocrMode": "auto",
  "tableMode": "fast",
  "maxDocuments": 1,
  "maxPagesPerDocument": 20,
  "maxFileSizeMb": 10,
  "downloadTimeoutSeconds": 60,
  "documentTimeoutSeconds": 180,
  "conversionMemoryLimitMb": 3072,
  "saveDocumentMarkdown": true,
  "failRunOnDocumentError": false
}