# PDF Table Extractor - PDF to CSV, Excel & JSON (`tidybytetools/pdf-table-pull`) Actor

Pull every table out of PDF files, even tables that run across pages. Get clean rows as JSON or CSV plus an Excel file per PDF. Reads scanned PDFs with OCR. $0.003 per page with a table; pages with no tables are free.

- **URL**: https://apify.com/tidybytetools/pdf-table-pull.md
- **Developed by:** [Tidy Byte Tools](https://apify.com/tidybytetools) (community)
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 page with a tables

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## PDF Table Extractor - PDF to CSV, Excel & JSON

Give it links to PDF files and it pulls out every table: bank statements, invoices, price lists, reports, government data. Each table lands in the dataset as clean rows (export as JSON, CSV or Excel from the Storage tab), and each PDF also gets its own Excel file with one sheet per table.

- Finds every table on every page, with or without border lines
- Joins a table that continues onto the next page into one table (repeated headers are dropped)
- Turns numbers into real numbers: `1,200` becomes 1200 and `(40)` becomes -40
- Reads scanned, image-only pages with OCR, built in, no setup
- A bad link doesn't stop the run. You get an item with an `error` field and it moves on

### Pricing

Pay only for pages that gave you a table:

| Event | Price | When |
|---|---|---|
| Page with a table | **$0.003** | A normal (text) PDF page where we found at least one table |
| Scanned page read with OCR | **$0.01** | A scanned (picture) page we read with OCR and found a table. Charged instead of the $0.003, not on top |

Apify also adds its small standard start fee per run.

You don't pay for:

- pages where no table was found
- links that fail to download or aren't PDFs

You're charged only after a PDF's rows and Excel file are saved. Set "Max pages per PDF" or a maximum cost per run. The Actor stops before your limit and tells you in the dataset.

| What you run | Pages with tables | Cost |
|---|---|---|
| One 3-page bank statement | 3 | $0.009 |
| 20 invoices, 1 page each | 20 | $0.06 |
| A 100-page report, 40 pages have tables | 40 | $0.12 |
| 1,000 pages of price lists | 1,000 | $3.00 |
| A 10-page scanned statement | 10 (OCR) | $0.10 |

### Input

| Field | What it means |
|---|---|
| PDF links | Direct links to PDF files. The link must download the PDF itself |
| Pages | Like `1,3-5`. Leave empty for all pages |
| Table type | Auto (default), tables with borders, or tables lined up by spacing |
| Scanned PDFs (OCR) | Auto (only pages with no text), every page, or off |
| Join tables across pages | On by default |
| Max pages per PDF | Default 200, so a huge file can't surprise you |

Example input:

```json
{
  "pdfUrls": [{ "url": "https://www.w3.org/WAI/WCAG21/working-examples/pdf-table/table.pdf" }],
  "pages": "",
  "strategy": "auto",
  "ocr": "auto",
  "mergeAcrossPages": true,
  "maxPagesPerPdf": 200
}
```

### Output

One dataset item per table:

```json
{
  "sourceUrl": "https://example.com/quarterly-report.pdf",
  "table": "page1_table1",
  "page": 1,
  "ocr": false,
  "columns": ["Region", "Q1", "Q2"],
  "records": [
    { "Region": "North", "Q1": 1200, "Q2": 1350 },
    { "Region": "South", "Q1": 980, "Q2": -40 }
  ],
  "rowCount": 2,
  "excelFile": "tables-1"
}
```

The Excel file for the first PDF is saved in the run's key-value store as `tables-1`, the second as `tables-2`, and so on.

A link that fails gives an item like this, and the run carries on:

```json
{ "sourceUrl": "https://example.com/missing.pdf", "error": "Client error '404 Not Found' for url 'https://example.com/missing.pdf'" }
```

### For AI agents

- **Use when:** you have public links to PDFs and need their tables as rows (JSON) or an Excel file.
- **Don't use when:** the PDF is behind a login, has a password, or you only need the plain text (not tables).
- **Input:** `pdfUrls` (list of `{"url": "..."}`), optional `pages` like `1,3-5`, `strategy` (`auto`, `lines`, `text`), `ocr` (`auto`, `always`, `never`), `mergeAcrossPages` (true/false), `maxPagesPerPdf`.
- **Output:** one dataset item per table with `sourceUrl`, `table`, `page`, `ocr`, `columns`, `records`, `rowCount`, `excelFile`. A failed link gives `{sourceUrl, error}`. No tables gives one item with `table: null` and `pagesCharged: 0`.
- **Cost:** $0.003 per page with a table, $0.01 per scanned page read with OCR. Pages with no tables are free. The run never goes over your max cost.
- Files are not kept after the run. Only your results stay in your own Apify storage.

### Run it on a schedule

If the same PDF is republished every week or month (a price list, a public report, a statement), create a **Task** with your links, then open **Schedules** in Apify Console and run it daily, weekly or monthly. Connect the run to Google Sheets, Make, Zapier, a webhook or the API to send the new rows wherever you need them.

### FAQ

**Does it work on scanned PDFs?**
Yes. Pages with no text layer are read with OCR automatically. OCR pages cost $0.01 because they take much more computer time. OCR is slower and can misread blurry scans, so check the numbers on those pages. Each item has `"ocr": true` when it came from OCR.

**A table came out wrong or wasn't found.**
Try "Table type: tables lined up by spacing" for tables without border lines, or "tables with borders" if spacing splits columns badly. Very unusual layouts may still need a quick fix by hand.

**Can it open password-protected PDFs?**
Not in this Actor. The offline version below can.

**Do you keep my PDFs?**
Files are downloaded into the run, processed, and only the results stay in your own Apify storage, under your storage retention settings.

**How do I get CSV?**
Open the dataset and export as CSV, or use the Excel file from the key-value store.

**Can I keep the files off the cloud entirely?**
Yes. Use the offline version.

### Prefer to run it on your own computer?

The same extractor is available as a Python tool you run offline, with no per-page cost. It also opens password-protected PDFs and writes Excel, CSV or JSON: **[pdf-table-pull on Gumroad](https://tidybyte.gumroad.com/l/hkxqxh)**. There's also a free CSV-only version, `pdf-table-pull-lite` (`pip install git+https://github.com/tidybytetools/pdf-table-pull-lite`), which also has a free MCP server for AI apps.

# Actor input Schema

## `pdfUrls` (type: `array`):

Direct links to the PDF files (the link must download the PDF itself, not a page showing it).

## `pages` (type: `string`):

Which pages to read, like 1,3-5. Leave empty for all pages.

## `strategy` (type: `string`):

Auto works for most files.

## `ocr` (type: `string`):

Reads scanned (picture) pages with OCR. A scanned page with a table costs $0.01 instead of $0.003.

## `mergeAcrossPages` (type: `boolean`):

When a table runs onto the next page, join it into one table and drop the repeated header row.

## `maxPagesPerPdf` (type: `integer`):

We read at most this many pages from each PDF. Keeps costs in check on very long files.

## Actor input object example

```json
{
  "pdfUrls": [
    {
      "url": "https://www.w3.org/WAI/WCAG21/working-examples/pdf-table/table.pdf"
    }
  ],
  "strategy": "auto",
  "ocr": "auto",
  "mergeAcrossPages": true,
  "maxPagesPerPdf": 200
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `files` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "pdfUrls": [
        {
            "url": "https://www.w3.org/WAI/WCAG21/working-examples/pdf-table/table.pdf"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("tidybytetools/pdf-table-pull").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "pdfUrls": [{ "url": "https://www.w3.org/WAI/WCAG21/working-examples/pdf-table/table.pdf" }] }

# Run the Actor and wait for it to finish
run = client.actor("tidybytetools/pdf-table-pull").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "pdfUrls": [
    {
      "url": "https://www.w3.org/WAI/WCAG21/working-examples/pdf-table/table.pdf"
    }
  ]
}' |
apify call tidybytetools/pdf-table-pull --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,tidybytetools/pdf-table-pull"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/aiGqg5pdflYACpJBP/builds/Hk31N5KOm1O0qEcQG/openapi.json