POST /batch/scrape

POST

batch

scrape

{
  "urls": ["https://example.com/a", "https://example.com/b"],
  "output": ["markdown"],
  "limit": 100
}

{
  "urls": ["https://example.com/products/1", "https://example.com/products/2"],
  "output": ["json"],
  "prompt": "Extract the product name, price, and availability.",
  "limit": 100
}

{
  "urls": ["https://example.com/a", "https://example.com/b"],
  "output": ["markdown"],
  "limit": 100,
  "email": "you@example.com",
  "webhook": {
    "url": "https://your-server.example.com/hooks/batch",
    "events": ["completed", "failed"]
  }
}

{
  "success": true,
  "id": "8a1c9e2e-4b7b-4a3a-9d0a-9b2a6e6f9c22",
  "url": "/batch/scrape/8a1c9e2e-4b7b-4a3a-9d0a-9b2a6e6f9c22"
}

{
  "detail": "Invalid batch scrape request."
}

{
  "detail": "Batch scraping is temporarily unavailable. Retry shortly."
}

Start a durable job that scrapes many URLs with the same options. The job runs as a background job — use the returned id to poll GET /batch/scrape/{id} for status and download links, or cancel it with DELETE /batch/scrape/{id}. All fields besides urls are the same per-page controls as POST /scrape (method, body, output, geolocation, session_id, tag, actions, prompt, schema), applied identically to every URL in the batch.

Authorization

Send your pline API key in the X-API-Key header on every request.

Body

string[]

required

Pages to scrape.

string

default:"GET"

HTTP method for every URL. One of GET, POST, PUT, DELETE.

object | string

Request body (JSON object or raw string), applied to every URL. Not supported with method: GET.

boolean

Controls browser rendering for every URL. Omit it and pline decides automatically; true forces a headless browser; false forbids a browser (not allowed together with actions or screenshot output).

string

Proxy cost tier to use for every URL. Omitting it escalates through the automatic set.

boolean

default:"true"

Remove navigation, footers, ads, and other non-main layout content from cleaned outputs (clean_html, markdown, json), applied to every page.

string[]

default:"[\"html\"]"

html, clean_html, links, markdown, screenshot, screenshot_full_page, or json (screenshot and screenshot_full_page are mutually exclusive).

string

2-letter ISO country code to route requests through.

string

Reuse cookies/headers across the batch (also accepts alias session).

string | string[]

Labels for filtering and tracing requests. Accepts one string or an array.

object[]

Browser actions applied to every URL, in order after each page loads. Same shape as POST /scrape’s actions.

Action	Needs	What it does
`click`	`selector`	Click an element.
`click_and_hold`	`selector`	Press and hold an element. Optional `duration_ms` (0–30,000, default 1,000).
`type`	`selector`, `value`	Type the `value` text into an element.
`hover`	`selector`	Move the pointer over an element.
`select_option`	`selector`, `value`	Choose the option `value` in a select element.
`press`	`selector`, `value`	Press the key in `value`, for example `Enter`, on an element.
`wait_for_selector`	`selector`	Wait until the element appears.
`scroll_into_view`	`selector`	Scroll an element into view.
`drag_to`	`selector`, `value`	Drag an element to the drop target whose selector is in `value`.
`scroll`	`value`	Scroll the page by `value` pixels (-100,000 to 100,000).
`wait`	`value`	Wait `value` milliseconds (0–30,000).
`reload`	none	Reload the page.

selector_type sets how selector is read: css (default), xpath, role, text, regex, test_id, label, or placeholder. Set frame_selector to search inside an iframe, and if_present: true to skip an action instead of failing when its selector isn’t visible.

integer

Per-page request timeout in milliseconds (1,000–60,000).

string

CSS selector to wait for before returning a browser-rendered page.

integer

Extra browser settle wait in milliseconds before returning (0–60,000).

string

Natural language extraction instruction, applied to every page, used when output includes json. prompt or schema is required when output includes json. prompt is limited to 16384 characters; schema is limited to 65536 bytes when serialized.

object

JSON schema for extracted data, applied to every page, used when output includes json. prompt or schema is required when output includes json. prompt is limited to 16384 characters; schema is limited to 65536 bytes when serialized.

integer

default:"10000"

Maximum URLs this job may process; also caps urls.length (max 10,000).

string

Address to notify by email once the batch completes. Must be a valid email address. See Delivery.

object

Optional webhook notified on batch lifecycle events. See Delivery for the payload and event types.

Show webhook properties

string

required

Webhook endpoint to notify. Must be HTTPS, point to a public host (no localhost or private IPs), and not contain credentials.

object

Extra headers to send with each webhook call.

any

Arbitrary JSON echoed back in every webhook payload.

string[]

Events to send. Empty means all events. One of started, completed, failed.

Response

boolean

required

Whether the batch scrape job was started.

string

required

Batch scrape job ID. Use this to poll status (GET /batch/scrape/{id}) or cancel (DELETE /batch/scrape/{id}).

string

required

Relative path to poll for this job’s status.

Response codes

Code	Meaning
`202`	Batch scrape job started
`422`	Invalid batch scrape request.
`503`	Batch scraping is temporarily unavailable. Retry shortly.

{
  "urls": ["https://example.com/a", "https://example.com/b"],
  "output": ["markdown"],
  "limit": 100
}

{
  "urls": ["https://example.com/products/1", "https://example.com/products/2"],
  "output": ["json"],
  "prompt": "Extract the product name, price, and availability.",
  "limit": 100
}

{
  "urls": ["https://example.com/a", "https://example.com/b"],
  "output": ["markdown"],
  "limit": 100,
  "email": "you@example.com",
  "webhook": {
    "url": "https://your-server.example.com/hooks/batch",
    "events": ["completed", "failed"]
  }
}

{
  "success": true,
  "id": "8a1c9e2e-4b7b-4a3a-9d0a-9b2a6e6f9c22",
  "url": "/batch/scrape/8a1c9e2e-4b7b-4a3a-9d0a-9b2a6e6f9c22"
}

{
  "detail": "Invalid batch scrape request."
}

{
  "detail": "Batch scraping is temporarily unavailable. Retry shortly."
}

{
  "urls": ["https://example.com/a", "https://example.com/b"],
  "output": ["markdown"],
  "limit": 100
}

{
  "urls": ["https://example.com/products/1", "https://example.com/products/2"],
  "output": ["json"],
  "prompt": "Extract the product name, price, and availability.",
  "limit": 100
}

{
  "urls": ["https://example.com/a", "https://example.com/b"],
  "output": ["markdown"],
  "limit": 100,
  "email": "you@example.com",
  "webhook": {
    "url": "https://your-server.example.com/hooks/batch",
    "events": ["completed", "failed"]
  }
}

{
  "success": true,
  "id": "8a1c9e2e-4b7b-4a3a-9d0a-9b2a6e6f9c22",
  "url": "/batch/scrape/8a1c9e2e-4b7b-4a3a-9d0a-9b2a6e6f9c22"
}

{
  "detail": "Invalid batch scrape request."
}

{
  "detail": "Batch scraping is temporarily unavailable. Retry shortly."
}

Scrape

Batch scrape

Map

Crawl

SERP

POST /batch/scrape

Authorization

Body

Response

Response codes

​Authorization

​Body

​Response

​Response codes

Authorization

Body

Response

Response codes