Browser API
Request parameters, behavior, and examples for the /v1 Browser API.
Browser API runs a real browser for pages that need rendering, waits, screenshots, JavaScript actions, custom target headers, or browser cookies.
Use this endpoint for Browser API requests:
| Base URL | Supported methods | Primary worker |
|---|---|---|
https://api.webscrapingapi.com/v1 | GET, POST, PUT, PATCH | Puppeteer-backed scraping browser |
Required parameters
| Parameter | Type | Notes |
|---|---|---|
api_key | string | Required for authentication. |
url | URL string | Required target URL. The decoded value must be a valid URL. |
Request parameters
| Parameter | Type | Validation and behavior |
|---|---|---|
method | GET, POST, PUT, PATCH | Sets the target request method. Use POST or PUT when forwarding a body. |
body | string | Forwarded to the target for body-capable Browser API requests. multipart/form-data target payloads are rejected. |
country | 2-letter code | Lowercased and used for proxy geotargeting. eu is accepted as a random Europe target. |
device | string | Browser device profile. Supported profiles include desktop, tablet, mobile, and none. |
timeout | number | Maximum request timeout. |
wait_until | string | One of load, domcontentloaded, networkidle0, networkidle2. |
wait_for | number | Milliseconds to wait after navigation. Allowed range: 100 to 60000. |
wait_for_css | string | CSS selector to wait for. |
window_width | number | Browser viewport width, 1 to 10000. |
window_height | number | Browser viewport height, 1 to 10000. |
screenshot | boolean | 1/true returns one final screenshot after all instructions. For intermediate captures, use screenshot actions in js_instructions. |
screenshot_options | JSON string | Requires screenshot=1. Supports full_page, width, height, screenshot_selector, and return_html. full_page and screenshot_selector cannot be combined. |
extract_rules | JSON string | Extracts selected data from HTML. Mutually exclusive with json_dom=1. |
json_dom | boolean | Returns a parsed DOM-like JSON structure. Mutually exclusive with extract_rules. |
json_response | boolean | Wraps response body, headers, status, type, and metadata in JSON. |
js_instructions | URL-encoded JSON array | Runs browser actions after navigation. |
block_resources | comma-separated string or 0 | Blocks matching resource categories. 0 or false disables default blocking in redirect workflows. |
auto_solve | boolean | Requires wait_for_css or a js_instructions wait_for_css action. |
render_js and session are accepted for backward compatibility on /v1, but Browser API requests do not use them. Do not include them in new Browser API integrations.
Custom headers and cookies
For /v1, send target headers as request headers prefixed with WSA-. The API removes the prefix before forwarding them to the target browser page.
curl "https://api.webscrapingapi.com/v1?api_key=YOUR_API_KEY&url=https%3A%2F%2Fhttpbin.org%2Fheaders" \
-H "WSA-Accept-Language: en-US" \
-H "WSA-User-Agent: Mozilla/5.0"Send target cookies with WSA-Cookie; the API converts the header into browser cookies for the target domain.
curl "https://api.webscrapingapi.com/v1?api_key=YOUR_API_KEY&url=https%3A%2F%2Fexample.com" \
-H "WSA-Cookie: consent=1; region=us"JavaScript instructions
js_instructions must be a URL-encoded JSON array. Supported actions are:
click, click_and_navigate, click_and_wait_response, delete_element, focus, load_full_page, scrollInf, scrollPx, scrollTo, solve_captcha, submit, submit_and_navigate, typed_value, value, wait_for_css, download_file, download_file_native, select, and screenshot.
For GET target requests, screenshot actions capture named images at their exact
position in the sequence. Each action requires a unique name and accepts its own
options. Up to 10 captures and 20 MiB of combined checkpoint base64 data are
allowed. The response includes an ordered screenshots array of
{ name, mime_type, data } objects; data is raw JPEG base64. With
json_response=1, the array is at the envelope root and the usual body is
preserved. These actions do not require screenshot=1; that parameter retains
its final-capture behavior. Screenshot checkpoints use one shared request timeout
and cannot be combined with download actions or redirect_chain. Capture, limit,
and deadline errors fail the request without partial results. See
multiple screenshots
for complete options, readiness guidance, and examples in all supported languages.
Both download_file and download_file_native require the domain in the request's
url parameter to be whitelisted. Contact customer support
for approval; both actions use the same whitelist.
For GET requests, download_file_native returns a native browser download as
base64_string. Supply an HTTP(S) file_url or a selector identifying a link;
file_url takes precedence and does not require selector. Its optional timeout
limits the download rather than adding a delay. It accepts PDF and binary-stream
responses by default; use allowed_content_types for other MIME types. Supply the
target's exact URL: the action does not rewrite site-specific paths.
INSTRUCTIONS='[{"action":"wait_for_css","selector":"main","timeout":10000},{"action":"scrollPx","pixels":1200}]'
curl --get "https://api.webscrapingapi.com/v1" \
--data-urlencode "api_key=YOUR_API_KEY" \
--data-urlencode "url=https://example.com" \
--data-urlencode "js_instructions=$INSTRUCTIONS" \
--data-urlencode "json_response=1"Extraction rules
extract_rules must be a JSON object encoded as a string. Each rule can be either a selector string or an object with:
| Option | Values |
|---|---|
selector | CSS or XPath selector |
selector_type | css or xpath |
output | output field or nested rule |
all | 0 or 1 |
clean | 0 or 1 |
RULES='{"title":{"selector":"h1","output":"text","clean":1},"links":{"selector":"a","output":"@href","all":1}}'
curl --get "https://api.webscrapingapi.com/v1" \
--data-urlencode "api_key=YOUR_API_KEY" \
--data-urlencode "url=https://example.com" \
--data-urlencode "extract_rules=$RULES"For product-specific Browser API docs, see Browser API parameters and Browser API examples.