Parse

Parse reads documents and returns them as Markdown, page by page, and can extract fields as JSON. Pages with their own text are read directly; scanned pages are read with AI. It works on PDF, Word (DOCX, DOC), Excel (XLSX), PowerPoint (PPTX, PPT), OpenDocument (ODT, ODS, ODP), RTF, EPUB, CSV and HTML.

Quick example

Parse the first 3 pages of a PDF from a link:

curl -X POST https://api.spidra.io/api/parse \
  -H "Authorization: Bearer $SPIDRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://arxiv.org/pdf/1706.03762", "maxPages": 3 }'

const doc = await spidra.parse({ url: "https://arxiv.org/pdf/1706.03762", maxPages: 3 });

console.log(doc.pagesParsed, doc.creditsUsed);

doc = client.parse("https://arxiv.org/pdf/1706.03762", max_pages=3)

print(doc.pages_parsed, doc.credits_used)
# 3 3

A short document comes back in the same request (Markdown shortened):

{
  "jobId": "c5a8d5a2-b10e-44f5-8c9e-dbbd334d19d1",
  "status": "completed",
  "fileName": "1706.03762",
  "sourceUrl": "https://arxiv.org/pdf/1706.03762",
  "fileId": "29273629-c557-4ac8-9e36-14fb96b1018d",
  "format": "PDF",
  "totalPages": 15,
  "pagesParsed": 3,
  "creditsUsed": 3,
  "markdown": "### Provided proper attribution is provided, Google hereby grants permission to\n\nreproduce the tables and figures in this paper...",
  "warnings": [],
  "metadata": { "totalPages": 15, "pagesParsed": 3, "ocrPages": 0 },
  "durationMs": 1005
}

The request waits up to 20 seconds. A longer document answers 202 with a jobId; poll GET /parse/{jobId}. The SDKs wait for you.

Three ways to send a document

A link: { "url": "https://..." }.

An upload: multipart/form-data with a file part (up to 50 MB) and an optional options part holding the other options as a JSON string.

curl -X POST https://api.spidra.io/api/parse \
  -H "Authorization: Bearer $SPIDRA_API_KEY" \
  -F "[email protected]" \
  -F 'options={"pages":"1-5"}'

A fileId from an earlier parse or estimate: parse the same file again (other pages, another prompt) without sending it. Files are kept for 24 hours.

For files up to 500 MB, use a prepared upload.

See the cost first

Add "dryRun": true to get the page count and credits without parsing or charging anything:

{ "url": "https://arxiv.org/pdf/1706.03762", "pages": "2-3", "dryRun": true }

{ "status": "estimate", "fileId": "0b007010-b3f6-4398-a3ba-e5c2518839c8", "fileName": "1706.03762", "format": "PDF", "totalPages": 15, "pagesToParse": 2, "credits": 2 }

Then parse it by fileId, without fetching it again:

est = client.estimate_parse("https://arxiv.org/pdf/1706.03762", pages="1-2")
doc = client.parse(file_id=est.file_id, pages="1-2")

Extract fields as JSON

Add a prompt, a schema, or both:

{
  "url": "https://arxiv.org/pdf/1706.03762",
  "pages": "1",
  "prompt": "The paper's title and the authors' names",
  "schema": {
    "type": "object",
    "properties": { "title": { "type": "string" }, "authors": { "type": "array", "items": { "type": "string" } } }
  }
}

The fields come back in json, next to the Markdown:

{ "title": "Attention Is All You Need", "authors": ["Ashish Vaswani", "Noam Shazeer", "Niki Parmar", "Jakob Uszkoreit", "Llion Jones", "Aidan N. Gomez", "Łukasz Kaiser", "Illia Polosukhin"] }

That cost 2 credits: 1 for the page and 1 for the AI. Use a schema when code reads the result; without one, json can come back as text.

Options

Option	Default	What it does
`mode`	`"auto"`	`"auto"` reads each page’s text and uses AI only for scans. `"fast"` never uses AI (scanned pages error and aren’t charged). `"ocr"` uses AI on every page.
`pages`	all	PDF page ranges: `"1-5"`, `"1-3, 8"`, `"10-"`.
`maxPages`		At most this many pages, after `pages`.
`includePages`	`false`	Also return each page on its own in `pages`, with how it was read (`"text"` or `"ocr"`).
`pageMarkers`	`false`	Put `<!-- page N -->` before each page in `markdown`.
`prompt`, `schema`		Fields to extract into `json`.
`dryRun`	`false`	Estimate only. Free.
`wait`	`true`	Wait up to 20 seconds. `false` returns the `jobId` straight away.

With includePages:

"pages": [
  { "pageNumber": 1, "markdown": "### Provided proper attribution is provided...", "method": "text" },
  { "pageNumber": 2, "markdown": "# 1 Introduction\n\nRecurrent neural networks, long short-term...", "method": "text" }
]

Many documents

POST /parse/batch takes up to 50 documents at once, mixing uploads, links and fileIds. Each becomes its own job, and one that fails doesn’t stop the others.

Cost

1 credit per page parsed, including pages read with AI. Formats other than PDF count one page per 3,000 characters of output. Extraction adds AI credits. Estimates, pages that can’t be read, documents that fail, status checks and deletes are free.

Privacy

Files are kept for 24 hours so you can parse them again, then deleted. Delete one sooner with DELETE /parse/files/{fileId}.

Limits

50 MB per upload, 500 MB with a prepared upload.
2,000 pages per document per request.
50 documents per batch, 60 parse requests a minute.

Complex tables, multi-column pages and handwriting can come out imperfect, and scanned pages depend on scan quality.

In the dashboard

Open Parse in the sidebar, drop files or paste links, and each one shows its pages and credits before anything runs. Choose How to read pages (Auto, Text only or Every page), Pages, and What to extract (with Use a schema). Results have Markdown, Pages and JSON tabs, with copy and download.

Parse results with three documents done and the per-page view open

Parse or scrape?

Scrape also turns a document link into Markdown. Use Parse for uploads, page ranges, per-page output, a cost estimate first, many documents, or files over 50 MB. Use Scrape when the document is one link among web pages you’re already scraping.

Turn a folder of PDFs into JSON

A complete script.

Map

Find a site’s PDFs to parse.

Structured output

Schemas for exact fields.

API reference

Every field and response.

Get started

Tools

Ready-made data

Getting the data you want

Supported sites

Guides

Dashboard

Account and billing

Quick example

Three ways to send a document

See the cost first

Extract fields as JSON

Options

Many documents

Cost

Privacy

Limits

In the dashboard

Parse or scrape?

Next

Turn a folder of PDFs into JSON

Map

Structured output

API reference

​Quick example

​Three ways to send a document

​See the cost first

​Extract fields as JSON

​Options

​Many documents

​Cost

​Privacy

​Limits

​In the dashboard

​Parse or scrape?

​Next

Turn a folder of PDFs into JSON

Map

Structured output

API reference

Quick example

Three ways to send a document

See the cost first

Extract fields as JSON

Options

Many documents

Cost

Privacy

Limits

In the dashboard

Parse or scrape?

Next