> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spidra.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Parse

> Turn PDF, Word, Excel, PowerPoint and other documents into Markdown page by page, or into JSON fields, by upload or link. See the cost before you 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:

```bash curl theme={null}
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 }'
```

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

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

```python Python theme={null}
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):

```json theme={null}
{
  "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}](https://docs.spidra.io/api-reference/parse/parse-status.md). 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.
  ```bash theme={null}
  curl -X POST https://api.spidra.io/api/parse \
    -H "Authorization: Bearer $SPIDRA_API_KEY" \
    -F "file=@report.pdf" \
    -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](https://docs.spidra.io/api-reference/parse/parse-uploads.md).

## See the cost first

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

```json theme={null}
{ "url": "https://arxiv.org/pdf/1706.03762", "pages": "2-3", "dryRun": true }
```

```json theme={null}
{ "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:

```python theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{ "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`:

```json theme={null}
"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](https://docs.spidra.io/api-reference/parse/parse-batch.md) 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}](https://docs.spidra.io/api-reference/parse/parse-delete-file.md).

## 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](https://mintcdn.com/spidra/Ew-SZt3zJq_nwjCD/images/parse-results.webp?fit=max\&auto=format\&n=Ew-SZt3zJq_nwjCD\&q=85\&s=2a6180d79d0cd0bad947377f76535a25)

## Parse or scrape?

[Scrape](https://docs.spidra.io/scrape.md) 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.

## Next

> **[Turn a folder of PDFs into JSON](https://docs.spidra.io/guides/pdfs-to-json.md)**
>
> A complete script.

> **[Map](https://docs.spidra.io/map.md)**
>
> Find a site's PDFs to parse.

> **[Structured output](https://docs.spidra.io/options/structured-output.md)**
>
> Schemas for exact fields.

> **[API reference](https://docs.spidra.io/api-reference/parse/parse.md)**
>
> Every field and response.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.