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

# Batch results

> Check a batch, read its pages and errors, retry failed pages, cancel it, delete its stored results and list your batches. Batches are kept for 24 hours.

Batches are read like crawls: polling, `next` paging, the status fields, `errors`, `maxTextLength` and webhooks work as in [Read a crawl](https://docs.stophy.dev/crawl/async.md), at `/v1/batch/scrape`. A batch and its pages are kept for 24 hours, then reading it returns `404 notFound`. These calls are not charged.

```bash cURL theme={null}
curl https://api.stophy.dev/v1/batch/scrape/$BATCH_ID \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

```typescript TypeScript theme={null}
import { Stophy } from "stophy";

const stophy = new Stophy();

const batch = await stophy.batch.scrape.status({ id: "<the id your batch returned>" });
console.log(batch.status, `${batch.completed} of ${batch.total}`);
```

```python Python theme={null}
from stophy import Stophy

stophy = Stophy()

batch = stophy.batch.scrape.status(id="<the id your batch returned>")
print(batch["status"], batch["completed"], "of", batch["total"])
```

```json theme={null}
{ "success": true, "status": "completed", "total": 2, "completed": 1, "failed": 1, "costUsd": 0.001 }
```

A page that answers `404` or `410` counts as `completed`, with `metadata.error` and no charge. `failed` counts pages that could not be read. Each page in `data` is a [scrape](https://docs.stophy.dev/scrape/overview) answer.

## Calls

| Call | What it does |
| - | - |
| `GET /v1/batch/scrape/{id}` | Counts and up to 100 finished pages or 2 MB, with `next`. |
| `GET /v1/batch/scrape/{id}/results` | Pages in parts. Send `limit` (20 by default, at most 100) and `cursor` with the same `limit` until `data.cursor` is missing. `data.results` holds the pages, `isTruncated` marks cut text, and failed pages appear in `data.errors` of the part where they landed. An error's `at` is Unix milliseconds here. |
| `GET /v1/batch/scrape/{id}/errors` | Failed pages, up to 1,000, with `isTruncated`. Each has `id`, `url`, `code`, `message`, `retryable`, and `at` and `timestamp` as date strings. `robotsBlocked` is always empty. |
| `DELETE /v1/batch/scrape/{id}` | Cancel. The pages already read are kept and charged. A batch that ended returns `409 jobFinished`. |
| `DELETE /v1/batch/scrape/{id}/results` | Remove stored pages early, once the batch is `completed`, `failed` or `cancelled`. `data.deletedPages` counts them, and reads then return an empty `results` with `message`. A running batch returns `400 invalidRequest`. |
| `GET /v1/batch/scrape` | Your batches, newest first, as `data.batches`. Send `status`, `limit` (1 to 100, default 20) and `cursor` until it is missing. |

The older `creditsUsed` field is a legacy field. Use `costUsd`.

## Retry failed pages

Read `/errors` and take the `url` of each row with `retryable: true`. Send them in `urls` to a new `POST /v1/batch/scrape` with the same options, or to the running batch with `appendToId`. Wait a few seconds before retrying `sourceUnavailable` and `sourceRefused`. Do not retry a row with `retryable: false`, such as `notFound`, `siteNotRead` or `promptInjectionDetected`. Codes are in [Errors](https://docs.stophy.dev/api-reference/errors.md) and retry timing in [Troubleshooting](https://docs.stophy.dev/production/troubleshooting.md). Batches share job limits with crawls: see [Rate limits](https://docs.stophy.dev/production/rate-limits.md).


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