> ## 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.

# Batches

> Read a list of URLs in the background with the same options as scrape. Submit once, get an id, then read the pages when they finish. $1 per 1,000 pages.

A batch reads a list of URLs in the background. You send the list once, get an `id` at once, and read the pages when they finish.

## Make a request

Get an API key in the [Quickstart](https://docs.stophy.dev/quickstart). Batches need an API key. This request reads four addresses as `markdown`. One is a page that does not exist, and one is not a website address.

```bash cURL theme={null}
curl -X POST https://api.stophy.dev/v1/batch/scrape \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com",
      "https://bun.com/docs/runtime/env",
      "https://bun.com/docs/this-page-does-not-exist",
      "ftp://example.com/file.txt"
    ],
    "formats": ["markdown"],
    "maxAge": 0
  }'
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/batch/scrape", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    urls: [
      "https://example.com",
      "https://bun.com/docs/runtime/env",
      "https://bun.com/docs/this-page-does-not-exist",
      "ftp://example.com/file.txt",
    ],
    formats: ["markdown"],
    maxAge: 0,
  }),
});
const batch = await response.json();
console.log(batch.id, batch.invalidURLs);
```

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

import requests

response = requests.post(
    "https://api.stophy.dev/v1/batch/scrape",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={
        "urls": [
            "https://example.com",
            "https://bun.com/docs/runtime/env",
            "https://bun.com/docs/this-page-does-not-exist",
            "ftp://example.com/file.txt",
        ],
        "formats": ["markdown"],
        "maxAge": 0,
    },
)
batch = response.json()
print(batch["id"], batch["invalidURLs"])
```

`maxAge: 0` reads every page live. See [Submit a batch](https://docs.stophy.dev/batches/submit.md) for every option.

## Read the response

The call answers at once, before any page is read. Starting a batch costs nothing.

```json theme={null}
{
  "success": true,
  "id": "job_WFIhxsA_0rgzF5l4imub_A",
  "url": "https://api.stophy.dev/v1/batch/scrape/job_WFIhxsA_0rgzF5l4imub_A",
  "invalidURLs": [
    "ftp://example.com/file.txt"
  ],
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "ce61987c-8879-4a47-b03f-f187567c166f"
}
```

Keep `id`. `url` is where to read the batch. `invalidURLs` lists the addresses that are not public website URLs. They are skipped, and the rest of the batch runs. An address sent twice is read once.

A few seconds later, `GET /v1/batch/scrape/{id}` returns the batch. This real answer is cut to a few lines of each page.

```json theme={null}
{
  "success": true,
  "data": [
    {
      "markdown": "This domain is for use in documentation examples without needing permi…",
      "metadata": {
        "title": "Example Domain",
        "sourceURL": "https://example.com/",
        "statusCode": 200,
        "contentType": "text/html",
        "cacheState": "miss",
        "scrapeId": "job_WFIhxsA_0rgzF5l4imub_A",
        "creditsUsed": 1,
        "costUsd": 0.001
      }
    },
    {
      "markdown": "# Environment Variables\n\n> Read and configure environment variables in…",
      "metadata": {
        "title": "Environment Variables",
        "sourceURL": "https://bun.com/docs/runtime/env",
        "statusCode": 200,
        "creditsUsed": 1,
        "costUsd": 0.001
      }
    },
    {
      "markdown": "[![](https://bun.com/logo.svg)Bun — home](https://bun.com/) …",
      "metadata": {
        "title": "Page not found — Bun",
        "sourceURL": "https://bun.com/docs/this-page-does-not-exist",
        "statusCode": 404,
        "creditsUsed": 0,
        "costUsd": 0,
        "error": "The page answered with status 404."
      }
    }
  ],
  "status": "completed",
  "total": 3,
  "completed": 3,
  "failed": 0,
  "creditsUsed": 1,
  "costUsd": 0.002,
  "createdAt": "2026-11-17T18:12:52.872Z",
  "completedAt": "2026-11-17T18:12:56.792Z",
  "duration": 3.92,
  "expiresAt": "2026-11-18T18:12:52.872Z",
  "errors": [],
  "requestId": "e832167b-5898-48ff-a1ff-aad0de856090"
}
```

Each page in `data` has the fields of a [scrape](https://docs.stophy.dev/scrape/overview) with `scrapeId` set to the batch id. `total` is the pages in the batch, `completed` the pages that came back, and `failed` the pages that could not be read, which are listed in `errors`. The 404 page came back, so it counts as `completed`, with its `error` in `metadata`, and it cost nothing. `costUsd` is what the batch has cost so far. `expiresAt` is when the batch and its pages are deleted. See [Results](https://docs.stophy.dev/batches/results.md).

## Status

| `status` | Meaning |
| - | - |
| `scraping` | The batch is waiting to start or reading pages. When it waits, `queuePosition` says where it is in line. |
| `completed` | Every page was tried. Some can still have failed: read `errors`. |
| `cancelled` | You stopped it. The pages already read are kept. |
| `failed` | The batch stopped. Your balance ran out, or no page could be read. `error` says which. |

`completed`, `cancelled` and `failed` are final. Poll the batch every few seconds, or send a `webhook` to be told as each page finishes and when the batch ends. See [Webhooks](https://docs.stophy.dev/webhooks.md).

## What a batch takes

You send the list and the options once, and every page is read the way [Scrape](https://docs.stophy.dev/scrape/overview) would read it.

| Field | What it does | Guide |
| - | - | - |
| `urls` | The pages or PDFs to read, 1 to 10,000. | [Submit](https://docs.stophy.dev/batches/submit.md) |
| `formats` and the scrape options | The outputs and options every page uses: `markdown`, `html`, `links`, `screenshot`, `json`, `actions`, `location` and the rest | [Scrape](https://docs.stophy.dev/scrape/overview) |
| `webhook` | Where to be told about each page and the end | [Submit](https://docs.stophy.dev/batches/submit.md#get-told-when-pages-finish) |
| `appendToId` | Add URLs to a batch that is still running | [Submit](https://docs.stophy.dev/batches/submit.md#add-urls-to-a-running-batch) |
| `maxConcurrency` | The most pages read at once | [Submit](https://docs.stophy.dev/batches/submit.md#options) |
| `Idempotency-Key` header | Make a retried submit return the same batch | [Submit](https://docs.stophy.dev/batches/submit.md#send-the-same-batch-twice-safely) |

## Price

A page costs what a scrape costs: $1 per 1,000 pages. A page that comes back with a 404 or 410 status, or cannot be read, costs nothing. `json` with a schema or a prompt, `summary`, `highlights`, `question`, `product`, `menu` and `changeTracking` in `json` mode add $3 per 1,000 pages each when they return something. Each page is charged when it finishes, and starting the batch is free. A batch that reads 10,000 pages costs \$10. See [Pricing](https://docs.stophy.dev/account/pricing.md).

## Choose another API

* [Scrape](https://docs.stophy.dev/scrape/overview) reads one page and answers in the same call.
* [Crawl](https://docs.stophy.dev/crawl/overview) finds the pages of a site for you and reads them in the background.
* [Map](https://docs.stophy.dev/map/overview) lists the pages of a site, to put in a batch.
* [Monitors](https://docs.stophy.dev/monitors/overview) read a page on a schedule and tell you when it changes.
* [Browser sessions](https://docs.stophy.dev/browser/overview) give you a browser to drive yourself.


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