WebScrapingAPI Docs

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 URLSupported methodsPrimary worker
https://api.webscrapingapi.com/v1GET, POST, PUT, PATCHPuppeteer-backed scraping browser

Required parameters

ParameterTypeNotes
api_keystringRequired for authentication.
urlURL stringRequired target URL. The decoded value must be a valid URL.

Request parameters

ParameterTypeValidation and behavior
methodGET, POST, PUT, PATCHSets the target request method. Use POST or PUT when forwarding a body.
bodystringForwarded to the target for body-capable Browser API requests. multipart/form-data target payloads are rejected.
country2-letter codeLowercased and used for proxy geotargeting. eu is accepted as a random Europe target.
devicestringBrowser device profile. Supported profiles include desktop, tablet, mobile, and none.
timeoutnumberMaximum request timeout.
wait_untilstringOne of load, domcontentloaded, networkidle0, networkidle2.
wait_fornumberMilliseconds to wait after navigation. Allowed range: 100 to 60000.
wait_for_cssstringCSS selector to wait for.
window_widthnumberBrowser viewport width, 1 to 10000.
window_heightnumberBrowser viewport height, 1 to 10000.
screenshotboolean1/true returns one final screenshot after all instructions. For intermediate captures, use screenshot actions in js_instructions.
screenshot_optionsJSON stringRequires screenshot=1. Supports full_page, width, height, screenshot_selector, and return_html. full_page and screenshot_selector cannot be combined.
extract_rulesJSON stringExtracts selected data from HTML. Mutually exclusive with json_dom=1.
json_dombooleanReturns a parsed DOM-like JSON structure. Mutually exclusive with extract_rules.
json_responsebooleanWraps response body, headers, status, type, and metadata in JSON.
js_instructionsURL-encoded JSON arrayRuns browser actions after navigation.
block_resourcescomma-separated string or 0Blocks matching resource categories. 0 or false disables default blocking in redirect workflows.
auto_solvebooleanRequires 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:

OptionValues
selectorCSS or XPath selector
selector_typecss or xpath
outputoutput field or nested rule
all0 or 1
clean0 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.

On this page