# Start a batch scrape (/docs/reference/batch-scrape)

Scrapes many URLs in the background and returns a batch scrape ID right away. Invalid URLs are skipped and listed. Once the batch scrape ends, its results are packaged into one file, downloaded from the status package url.

`POST /v2/batch/scrape`

Requires an API key.

## Example request

```sh
curl -X POST 'https://api.elisebot.dev/v2/batch/scrape' \
  -H "Authorization: Bearer $ELISEBOT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "urls": [
      "…"
    ]
  }'
```

## Parameters

- `Idempotency-Key` (header, string): A unique key, such as a UUID, to safely retry the request. Valid for 24 hours. At most 255 characters. Pattern ^[\x21-\x7e]+$.

## Request body

`application/json`, required.

Type: `BatchScrapeRequest`

- `ignoreInvalidURLs` (boolean): Skip invalid URLs instead of rejecting the request. Default `true`.
- `requestOptions` (RequestOptions): Options for the requests sent to the URLs.
  - `headers` (array of RequestHeader or null): Headers to send, in this order and exactly as written. Omit to use the defaults. Redirect hops also carry the cookies the site sets. With headers, redirects to another site are not followed.
    - `name` (string, required): The header name. At least 1 characters.
    - `value` (string, required): The header value.
- `responseOptions` (ResponseOptions): Options for the content returned for each URL.
  - `format` (string): The format to return the page in. One of `html`, `markdown`. Default `html`.
  - `onlyMainContent` (boolean): Return only the page's main content, without navigation, headers and footers. Default `false`.
- `urls` (array of string or null, required): The URLs to scrape. At least 1 items.
- `webhook` (Webhook): Get notified as the batch scrape progresses.
  - `events` (array of string or null): Events to send. Defaults to all. One of `start`, `finish`. At least 1 items.
  - `headers` (map of string): Headers to include with each event.
  - `metadata` (map of string): Custom data included with each event.
  - `secret` (string): A secret to sign each event with, sent in the X-Webhook-Signature header.
  - `url` (string, required): The endpoint that receives events. Failed deliveries are retried. At least 1 characters. At most 2048 characters.

## Responses

### 200

OK.

Headers:

- `Idempotent-Replayed` (string): True when the response replays an earlier request with the same key. One of `true`.

Type: `BatchScrapeResponse`

- `id` (string, required): The batch scrape ID.
- `invalidURLs` (array of string, required): URLs skipped as invalid.
- `success` (boolean, required): Always true. One of `true`.
- `url` (string, required): The URL to check the batch scrape status.

### 400

MALFORMED_REQUEST: The request body is missing or is not valid JSON.

Type: `MalformedRequestResponse`

- `code` (string, required): A machine-readable error code. One of `MALFORMED_REQUEST`.
- `details` (array of ValidationErrorDetail or null): The invalid fields.
  - `location` (string): Where the error occurred, e.g. body.urls[3].
  - `message` (string): What went wrong.
  - `value` (any): The rejected value.
- `error` (string, required): A human-readable message.
- `success` (boolean, required): Always false. One of `false`.

### 401

UNAUTHORIZED: The API key is invalid or revoked; API_KEY_REQUIRED: This endpoint needs an API key; INVALID_ACCESS_TOKEN: The OAuth access token is unknown, expired or revoked, or was sent to an endpoint other than /mcp, the only one it works on.

Type: `UnauthorizedResponse`

- `code` (string, required): A machine-readable error code. One of `UNAUTHORIZED`, `API_KEY_REQUIRED`, `INVALID_ACCESS_TOKEN`.
- `details` (array of ValidationErrorDetail or null): The invalid fields.
  - `location` (string): Where the error occurred, e.g. body.urls[3].
  - `message` (string): What went wrong.
  - `value` (any): The rejected value.
- `error` (string, required): A human-readable message.
- `success` (boolean, required): Always false. One of `false`.

### 402

INSUFFICIENT_CREDITS: The credit balance does not cover the request's URLs.

Type: `PaymentRequiredResponse`

- `code` (string, required): A machine-readable error code. One of `INSUFFICIENT_CREDITS`.
- `details` (array of ValidationErrorDetail or null): The invalid fields.
  - `location` (string): Where the error occurred, e.g. body.urls[3].
  - `message` (string): What went wrong.
  - `value` (any): The rejected value.
- `error` (string, required): A human-readable message.
- `success` (boolean, required): Always false. One of `false`.

### 408

REQUEST_TIMEOUT: The request body took too long to arrive.

Type: `RequestTimeoutResponse`

- `code` (string, required): A machine-readable error code. One of `REQUEST_TIMEOUT`.
- `details` (array of ValidationErrorDetail or null): The invalid fields.
  - `location` (string): Where the error occurred, e.g. body.urls[3].
  - `message` (string): What went wrong.
  - `value` (any): The rejected value.
- `error` (string, required): A human-readable message.
- `success` (boolean, required): Always false. One of `false`.

### 413

PAYLOAD_TOO_LARGE: The request body is too large.

Type: `PayloadTooLargeResponse`

- `code` (string, required): A machine-readable error code. One of `PAYLOAD_TOO_LARGE`.
- `details` (array of ValidationErrorDetail or null): The invalid fields.
  - `location` (string): Where the error occurred, e.g. body.urls[3].
  - `message` (string): What went wrong.
  - `value` (any): The rejected value.
- `error` (string, required): A human-readable message.
- `success` (boolean, required): Always false. One of `false`.

### 415

UNSUPPORTED_MEDIA_TYPE: The request body must be JSON.

Type: `UnsupportedMediaTypeResponse`

- `code` (string, required): A machine-readable error code. One of `UNSUPPORTED_MEDIA_TYPE`.
- `details` (array of ValidationErrorDetail or null): The invalid fields.
  - `location` (string): Where the error occurred, e.g. body.urls[3].
  - `message` (string): What went wrong.
  - `value` (any): The rejected value.
- `error` (string, required): A human-readable message.
- `success` (boolean, required): Always false. One of `false`.

### 422

VALIDATION_FAILED: One or more fields are invalid; TOO_MANY_URLS: The request has more URLs than your rate limit allows; IDEMPOTENCY_CONFLICT: The Idempotency-Key was already used with a different request.

Type: `ValidationFailedResponse`

- `code` (string, required): A machine-readable error code. One of `VALIDATION_FAILED`, `TOO_MANY_URLS`, `IDEMPOTENCY_CONFLICT`.
- `details` (array of ValidationErrorDetail or null): The invalid fields.
  - `location` (string): Where the error occurred, e.g. body.urls[3].
  - `message` (string): What went wrong.
  - `value` (any): The rejected value.
- `error` (string, required): A human-readable message.
- `success` (boolean, required): Always false. One of `false`.

### 429

RATE_LIMITED: Rate limit exceeded, retry after Retry-After seconds.

Headers:

- `Retry-After` (integer): Seconds to wait before retrying. Minimum 1.

Type: `TooManyRequestsResponse`

- `code` (string, required): A machine-readable error code. One of `RATE_LIMITED`.
- `details` (array of ValidationErrorDetail or null): The invalid fields.
  - `location` (string): Where the error occurred, e.g. body.urls[3].
  - `message` (string): What went wrong.
  - `value` (any): The rejected value.
- `error` (string, required): A human-readable message.
- `success` (boolean, required): Always false. One of `false`.

### 500

INTERNAL_ERROR: Something went wrong on our side, try again.

Type: `InternalErrorResponse`

- `code` (string, required): A machine-readable error code. One of `INTERNAL_ERROR`.
- `details` (array of ValidationErrorDetail or null): The invalid fields.
  - `location` (string): Where the error occurred, e.g. body.urls[3].
  - `message` (string): What went wrong.
  - `value` (any): The rejected value.
- `error` (string, required): A human-readable message.
- `success` (boolean, required): Always false. One of `false`.