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

# PDFs and documents

> Scrape a PDF, Word, PowerPoint, Excel or CSV file from a public URL and get Markdown. Pick the pages, read scanned pages, and keep page markers.

Send the public URL of a document, and Scrape returns its text as Markdown, the same way it reads a page. To read a file from your own disk, use [Parse documents](https://docs.stophy.dev/parse/overview).

## Make a request

Get an API key in the [Quickstart](https://docs.stophy.dev/quickstart). This request reads the first two pages of a research paper and marks where each page starts.

```bash cURL theme={null}
curl -X POST https://api.stophy.dev/v1/scrape \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://arxiv.org/pdf/1706.03762",
    "parsers": [
      { "type": "pdf", "maxPages": 2, "pageMarkers": true }
    ]
  }'
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/scrape", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://arxiv.org/pdf/1706.03762",
    parsers: [{ type: "pdf", maxPages: 2, pageMarkers: true }],
  }),
});
const { data } = await response.json();
console.log(data.metadata.numPages);
console.log(data.markdown);
```

```python Python theme={null}
import os

import requests

response = requests.post(
    "https://api.stophy.dev/v1/scrape",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={
        "url": "https://arxiv.org/pdf/1706.03762",
        "parsers": [{"type": "pdf", "maxPages": 2, "pageMarkers": True}],
    },
)
data = response.json()["data"]
print(data["metadata"]["numPages"])
print(data["markdown"])
```

## Read the response

The text is in `data.markdown`. Page 2 starts after a `---` line and a `<!-- page 2 -->` marker. This real response is cut. Each page's text is shortened.

```json theme={null}
{
  "success": true,
  "data": {
    "markdown": "## Provided proper attribution is provided, Google hereby grants permission to reproduce the tables and figures in this paper solely for use in journalistic or scholarly works.\n\n# Attention Is All You Need\n\nAshish Vaswani∗\nGoogle Brain\n…\n\n---\n\n<!-- page 2 -->\n\n## 1 Introduction\n\nRecurrent neural networks, long short-term memory [13] and gated recurrent …",
    "warning": "The page text was cut short.",
    "metadata": {
      "sourceURL": "https://arxiv.org/pdf/1706.03762",
      "url": "https://arxiv.org/pdf/1706.03762",
      "statusCode": 200,
      "contentType": "application/pdf",
      "numPages": 15,
      "totalPages": 15,
      "cacheState": "miss",
      "scrapeId": "c2dc2abc-e285-4f8a-84b6-717c231eab35",
      "costUsd": 0.002
    }
  },
  "id": "c2dc2abc-e285-4f8a-84b6-717c231eab35",
  "costUsd": 0.002,
  "requestId": "c2dc2abc-e285-4f8a-84b6-717c231eab35"
}
```

`contentType` says what the file is. `totalPages` is the pages in the file, and `ocrPages` appears when some pages were read from their picture. A PDF always comes back as Markdown.

## Options

Send the PDF options in `parsers`, as `"pdf"` or as an object.

| Field | Type | Default | Effect |
| - | - | - | - |
| `type` | `string` | none | `"pdf"`. Required in the object form. |
| `mode` | `string` | `"auto"` | `fast` reads the text layer only. `auto` reads the text layer, and reads the picture of any page that has none. `ocr` reads the picture of every page. |
| `maxPages` | `number` | `500` | Read at most this many pages, 1 to 500. |
| `pages` | `boolean` | `false` | Also return each page's Markdown in `pages`, as `{ pageNumber, markdown }`. |
| `blocks` | `boolean` | `false` | Also return the layout in `blocks`: each title, section header or run of text, with its page, reading order, position on the page (`bbox` as left, top, right, bottom from 0 to 1) and where its text sits in that page's Markdown (`span`). Tables, figures and formulas are not told apart. |
| `pageMarkers` | `boolean` | `false` | Join pages with `---` and a `<!-- page N -->` line, where `N` is the page that follows. |

Stophy reads the picture of at most 20 pages per call, in `auto` or `ocr` mode. Without an API key, only the text layer is read.

## Other documents

* A CSV file comes back as a Markdown table, and so does each sheet of an Excel `.xlsx` file. The first row becomes the table header.
* A Word `.docx` or PowerPoint `.pptx` file comes back as Markdown text.
* The older `.doc`, `.xls` and `.ppt` formats cannot be read.

A NASA temperature CSV at `https://data.giss.nasa.gov/gistemp/tabledata_v4/GLB.Ts+dSST.csv`, read with `"maxChars": 500`, returned a table. This real response is cut to the fields that matter. The file's first line is a title, so the title is the table header.

```json theme={null}
{
  "success": true,
  "data": {
    "markdown": "| Land-Ocean: Global Means |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |\n| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |\n| Year | Jan | Feb | Mar | Apr | May | Jun | Jul | Aug | Sep | Oct | Nov | Dec | J-D | D-N | DJF | MAM | JJA | SON |\n| 1880 | -.19 | -.25 | -.10 | -.17 | -.10 | -.21 | -.19 | -.11 | -.15 | -.23 | -.22 | -.18 | -.18 | *** | *** | -.12 | -.17 | -.20 |\n",
    "nextOffset": 449,
    "warning": "The page text was cut short. Send offset 449 to read on.",
    "metadata": {
      "sourceURL": "https://data.giss.nasa.gov/gistemp/tabledata_v4/GLB.Ts+dSST.csv",
      "contentType": "text/csv",
      "statusCode": 200,
      "costUsd": 0.001
    }
  },
  "id": "c96db640-04a9-4179-8d86-833a4fa07acd",
  "costUsd": 0.001,
  "requestId": "c96db640-04a9-4179-8d86-833a4fa07acd"
}
```

## Limits and errors

* A file larger than 20 MB, or one that is too large once unpacked, returns `400 invalidRequest` and says so.
* A password-protected file, a file that cannot be opened, and a URL that is an image or another download return `400 invalidRequest` and name the problem.
* A PDF that takes too long to read returns `400 invalidRequest` and suggests a smaller `maxPages`.
* Combine `maxChars` and `offset` to read a long document part by part. See [Content filtering](https://docs.stophy.dev/scrape/content-filtering.md).

## Price

$1 per 1,000 pages for the read, plus $0.50 per 1,000 pages of PDF text from its text layer and $2.50 per 1,000 pages of text read from its picture, that come back. The example above read 2 pages of a PDF from their text layer and cost $0.002. A PDF read with `maxChars`, `offset` or `query` is charged for the share of its pages that it returns, at least 1 page. A file that cannot be read costs nothing.

## Related

* [Parse documents](https://docs.stophy.dev/parse/overview) turns a file you upload into Markdown.
* [Content filtering](https://docs.stophy.dev/scrape/content-filtering.md) cuts a long document into parts.
* [Page metadata](https://docs.stophy.dev/scrape/page-metadata.md) explains `numPages`, `totalPages` and `ocrPages`.
* [Scrape overview](https://docs.stophy.dev/scrape/overview) lists every format and option.


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