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

# Results

> Check a batch, read its pages a page at a time, list the pages that failed, delete the stored results, and find your earlier batches. Kept for 24 hours.

A batch and its pages are kept for 24 hours. Check the batch until its `status` is final, then read its pages, its errors, or both. All of these calls are free.

## Check status

Get an API key in the [Quickstart](https://docs.stophy.dev/quickstart). `GET /v1/batch/scrape/{id}` returns the counts and the finished pages. Poll it every few seconds while `status` is `scraping`.

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

```typescript TypeScript theme={null}
const id = "<the id your batch returned>";
const response = await fetch(`https://api.stophy.dev/v1/batch/scrape/${id}`, {
  headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}` },
});
const batch = await response.json();
console.log(batch.status, `${batch.completed} of ${batch.total}`, batch.costUsd);
```

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

import requests

batch_id = "<the id your batch returned>"
response = requests.get(
    f"https://api.stophy.dev/v1/batch/scrape/{batch_id}",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
)
batch = response.json()
print(batch["status"], batch["completed"], "of", batch["total"], batch["costUsd"])
```

This real batch read one page and could not read the other, because its domain does not exist. The page text is cut.

```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_FcxIcgRhtA3DhBn2UjZEFA",
        "creditsUsed": 1,
        "costUsd": 0.001
      }
    }
  ],
  "status": "completed",
  "total": 2,
  "completed": 1,
  "failed": 1,
  "creditsUsed": 1,
  "costUsd": 0.001,
  "createdAt": "2026-11-17T18:13:10.052Z",
  "completedAt": "2026-11-17T18:13:12.695Z",
  "duration": 2.643,
  "expiresAt": "2026-11-18T18:13:10.052Z",
  "errors": [
    {
      "id": "err_73cdb4935459e2da",
      "url": "https://this-domain-does-not-exist-stophy.com",
      "code": "notFound",
      "message": "That address has no website behind it. Check the spelling of the domain, then try again.",
      "retryable": false,
      "at": "2026-11-17T18:13:12.314Z"
    }
  ],
  "requestId": "4a3309b0-9ac9-4d52-a50c-3e52abc18d1d"
}
```

| Field | What it holds |
| - | - |
| `status` | `scraping`, `completed`, `cancelled` or `failed`. See [Batches](https://docs.stophy.dev/batches/overview#status). |
| `queuePosition` | Where the batch is in line, while it waits to start. |
| `total`, `completed`, `failed` | Pages in the batch, pages that came back, and pages that could not be read. |
| `creditsUsed`, `costUsd` | What the batch has cost so far. `creditsUsed` is the older field, in steps of \$0.002. |
| `createdAt`, `completedAt`, `duration` | When it started and ended, and how many seconds it took. |
| `expiresAt` | When the batch and its pages are deleted. |
| `data` | Up to 100 finished pages, or 2 MB. Each page is a [scrape](https://docs.stophy.dev/scrape/overview) answer. |
| `errors` | The pages that could not be read, each with a `code` and whether it is `retryable`. |
| `error` | Why the batch itself stopped, when `status` is `failed`. |
| `next` | The address of the next page of results, when more finished pages are waiting. |

A page that answered `404` or `410` is not an error. It counts as `completed`, its `metadata.error` says what happened, and it costs nothing.

## Read the results in parts

`GET /v1/batch/scrape/{id}/results` returns the same pages in a shape made for paging. Send `limit` and `cursor`.

```bash cURL theme={null}
BATCH_ID="<the id your batch returned>"
curl "https://api.stophy.dev/v1/batch/scrape/$BATCH_ID/results?limit=2" \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

```typescript TypeScript theme={null}
const id = "<the id your batch returned>";
const headers = { Authorization: `Bearer ${process.env.STOPHY_API_KEY}` };
const pages = [];
let cursor: string | undefined;
do {
  const url = new URL(`https://api.stophy.dev/v1/batch/scrape/${id}/results`);
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);
  const { data } = await (await fetch(url, { headers })).json();
  pages.push(...data.results);
  cursor = data.cursor;
} while (cursor);
console.log(pages.length);
```

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

import requests

batch_id = "<the id your batch returned>"
headers = {"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"}
pages = []
cursor = None
while True:
    params = {"limit": 100, **({"cursor": cursor} if cursor else {})}
    data = requests.get(
        f"https://api.stophy.dev/v1/batch/scrape/{batch_id}/results",
        headers=headers,
        params=params,
    ).json()["data"]
    pages.extend(data["results"])
    cursor = data.get("cursor")
    if not cursor:
        break
print(len(pages))
```

This real answer used `limit` 2. The page text is cut. The cURL tab reads one part, and the TypeScript and Python tabs read every part, 100 results at a time.

```json theme={null}
{
  "success": true,
  "data": {
    "id": "job_WFIhxsA_0rgzF5l4imub_A",
    "status": "completed",
    "total": 3,
    "completed": 3,
    "failed": 0,
    "creditsUsed": 1,
    "costUsd": 0.002,
    "errors": [],
    "results": [
      {
        "markdown": "This domain is for use in documentation examples without needing permi…",
        "isTruncated": false,
        "metadata": {
          "title": "Example Domain",
          "sourceURL": "https://example.com/",
          "statusCode": 200,
          "contentType": "text/html",
          "cacheState": "miss"
        },
        "url": "https://example.com",
        "creditsUsed": 1,
        "costUsd": 0.001
      },
      {
        "markdown": "# Environment Variables\n\n> Read and configure environment variables in…",
        "isTruncated": false,
        "metadata": {
          "title": "Environment Variables",
          "sourceURL": "https://bun.com/docs/runtime/env",
          "statusCode": 200
        },
        "url": "https://bun.com/docs/runtime/env",
        "creditsUsed": 1,
        "costUsd": 0.001
      }
    ],
    "cursor": "rplw_0tfpage_2"
  },
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "027413d7-81dc-4edc-95bd-aab743207c93"
}
```

`limit` is 20 by default and at most 100. Send `cursor` from the answer, with the same `limit`, to read the next part. A part can hold fewer results than `limit`, so keep going until there is no `cursor`. Each result has its own `url`, `creditsUsed` and `costUsd`.

Pages that failed show up in the `errors` of the part where they landed. This real second part of a two-page batch had no results and one error.

```json theme={null}
{
  "success": true,
  "data": {
    "id": "job_FcxIcgRhtA3DhBn2UjZEFA",
    "status": "completed",
    "total": 2,
    "completed": 1,
    "failed": 1,
    "errors": [
      {
        "url": "https://this-domain-does-not-exist-stophy.com",
        "code": "notFound",
        "message": "That address has no website behind it. Check the spelling of the domain, then try again.",
        "retryable": false,
        "at": 1794939192314
      }
    ],
    "results": []
  }
}
```

## Read the errors

`GET /v1/batch/scrape/{id}/errors` lists only the pages that could not be read, with the reason for each.

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

```json theme={null}
{
  "success": true,
  "status": "completed",
  "failed": 1,
  "errors": [
    {
      "id": "err_73cdb4935459e2da",
      "timestamp": "2026-11-17T18:13:12.314Z",
      "error": "That address has no website behind it. Check the spelling of the domain, then try again.",
      "url": "https://this-domain-does-not-exist-stophy.com",
      "code": "notFound",
      "message": "That address has no website behind it. Check the spelling of the domain, then try again.",
      "retryable": false,
      "at": "2026-11-17T18:13:12.314Z"
    }
  ],
  "robotsBlocked": [],
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "4a1ff560-bc22-4173-bc75-70a9db0251fe"
}
```

`code` is one of the [error codes](https://docs.stophy.dev/api-reference/errors.md). `retryable: true` means a new batch with that URL can work. `robotsBlocked` lists pages the site's robots rules kept Stophy from reading. At most 1,000 errors are listed, and `isTruncated` is `true` when there were more. See [Limits and errors](https://docs.stophy.dev/batches/limits-and-errors.md).

## Delete the results

`DELETE /v1/batch/scrape/{id}/results` removes the stored pages at once. It works once the batch is `completed`, `failed` or `cancelled`. The batch keeps its counts.

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

```json theme={null}
{
  "success": true,
  "data": {
    "id": "job_WFIhxsA_0rgzF5l4imub_A",
    "deletedPages": 3
  },
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "b8687973-d893-4307-925b-03a65618ec38"
}
```

After the delete, reading the results answers with the counts, an empty `results`, and `message` set to `The stored results were deleted.` Deleting again returns `deletedPages` of `0`. A batch that is still running returns `400 invalidRequest`: `This batch scrape has not finished, so its results cannot be deleted yet. Wait until its status is completed, failed or cancelled, then send the call again.` To stop a batch first, see [Limits and errors](https://docs.stophy.dev/batches/limits-and-errors.md#cancel-a-batch).

## List your batches

`GET /v1/batch/scrape` lists your batches, newest first, and is free.

| Query field | Type | Default | Effect |
| - | - | - | - |
| `status` | `string` | all | Only batches in this status: `scraping`, `completed`, `cancelled` or `failed`. |
| `limit` | `number` | `20` | Batches per page, 1 to 100. |
| `cursor` | `string` | none | `cursor` from the last answer. |

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

```json theme={null}
{
  "success": true,
  "data": {
    "batches": [
      {
        "id": "job_FcxIcgRhtA3DhBn2UjZEFA",
        "status": "completed",
        "total": 2,
        "completed": 1,
        "failed": 1,
        "creditsUsed": 1,
        "costUsd": 0.001,
        "createdAt": "2026-11-17T18:13:10.052Z",
        "completedAt": "2026-11-17T18:13:12.695Z",
        "expiresAt": "2026-11-18T18:13:10.052Z"
      },
      {
        "id": "job_WFIhxsA_0rgzF5l4imub_A",
        "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",
        "expiresAt": "2026-11-18T18:12:52.872Z"
      }
    ],
    "cursor": "r1hWm-iB1794939172872:job_WFIhxsA_0rgzF5l4imub_A"
  },
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "b5282986-a53a-4dd6-bc49-9456082f995b"
}
```

A page can hold fewer batches than `limit`, so keep sending `cursor` until it is missing. A batch that stopped early has its reason in `message`. Run this to confirm that no batch you started is still reading.

## Options

| Field | Where | Type | Default | Effect |
| - | - | - | - | - |
| `limit` | results and list query | `number` | `20` | 1 to 100. |
| `cursor` | status, results and list query | `string` | none | Where to read on from. |
| `status` | list query | `string` | all | Filter by status. |
| `maxTextLength` | any read | `number` | none | Cuts every text value to this many characters. A cut value ends with `…`, and `isTruncated` is `true`. |

## Limits and errors

* A batch, its pages and its errors are kept for 24 hours after it starts. After that, reading it returns `404 notFound`: `No batch scrape with that id. Results are kept for 24 hours.` Copy what you need before then.
* A status read returns at most 100 pages or 2 MB in one answer.
* An id that is not yours returns `404 notFound` too.

## Related

* [Batches](https://docs.stophy.dev/batches/overview) explains the statuses and the price.
* [Submit a batch](https://docs.stophy.dev/batches/submit.md) sends the list and the options.
* [Limits and errors](https://docs.stophy.dev/batches/limits-and-errors.md) covers cancelling and failed pages.
* [Results reference](https://docs.stophy.dev/api-reference/endpoint/batch-scrape-results.md) and [status reference](https://docs.stophy.dev/api-reference/endpoint/batch-scrape-status.md) list every field.


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