Handle client-rendered pages
Use browser-backed retrieval when required content appears only after page JavaScript has executed.
Review request controlsBrowser-API
Browser API for
JavaScript-heavy pages
and guided interactions.
Browser API is a request-response REST API: load a public page in a hosted browser, wait for the state your workflow needs, execute documented actions, and return a usable output. It does not expose a live browser-control connection.
- State-aware waits Lifecycle, delay, or selector
- Guided actions Click, scroll, type, select, submit
- Anforderungskontext Device, viewport, country
- Selectable output HTML, JSON, fields, screenshot
A clearer browser boundary
Reach the rendered state you need without operating browser workers.
Describe the request, readiness condition, interaction sequence, and output. WebScrapingAPI operates the hosted browser execution behind that contract.
Capture a deliberate page state
Wait for a lifecycle event, delay, selector, or documented instruction step instead of parsing whatever happens to arrive first.
See the request workflowChoose the useful response
Return rendered HTML, a JSON response, a JSON DOM, selected fields, or a screenshot for the downstream task.
Compare output optionsYour application definesURL · context · readiness · actions · output
WebScrapingAPI operatesHosted browser execution and response delivery
Your pipeline receivesOne documented response or explicit error
Request anatomy
Configure context, readiness, interaction, and capture in one request.
Start with the target URL and add only the documented controls required to reproduce the page state your application needs. Review exact names and accepted values in the Browser API parameter guide.
Anforderungskontext
Define how the hosted browser reaches and frames the page.
api_key- Server-side authentication
url- URL-encoded public target
method- Target request method
body- Optional target body
country- Supported country context
timeout- Request time budget
device- Desktop, mobile, or tablet
window_width- Viewport width
window_height- Viewport height
block_resources- Optional resource blocking
Readiness and actions
Tell the request when the page is ready and what to do next.
wait_until- Lifecycle state
wait_for- Explicit delay
wait_for_css- Required selector
js_instructions- Ordered interaction sequence
auto_solve- Documented access control
clickscrollTotyped_valueselectsubmitclick_and_navigateCapture and response
Select what the browser-backed request should return.
screenshot- Request image capture
screenshot_options- Capture scope and dimensions
extract_rules- Customer-supplied CSS or XPath rules
json_response- JSON response envelope
json_dom- JSON DOM representation
Use the smallest stable recipe.
Prefer an observable selector or lifecycle state over arbitrary delay, keep action sequences short, and validate the returned content against your own business requirements.
Request workflow
Turn page behavior into an explicit request recipe.
The browser runtime is managed by WebScrapingAPI. Your application still defines the intended state and decides whether the returned content is fit for use.
- 01request
Define the target
Provide the URL, method, country, device, viewport, and timeout required for the test case.
- 02state
Reach readiness
Choose
domcontentloaded,load,networkidle0,networkidle2, a delay, or a selector. - 03interaction
Execute actions
Apply an ordered
js_instructionssequence when the page needs clicks, scrolling, values, selections, or navigation. - 04output
Return and validate
Receive the requested format or explicit error, then validate content before it enters the downstream system.
- Prefer
- Observable readiness
A selector or page lifecycle condition tied to the content you need.
- Keep
- Instructions minimal
Only the actions required to reach a stable, repeatable state.
- Expect
- Explicit outcomes
Browser execution can still fail, time out, or return content that needs business validation.
Output contract
Return the representation your next system can use.
Capture the rendered page once, then choose a documented output that fits an existing parser, validation step, evidence record, or media workflow.
Plain HTML
Return the rendered page body for a parser or archive process your team operates.
text/htmlJSON envelope
Wrap the body with documented request and target-response context for inspection.
json_responseJSON DOM
Receive the page document as a JSON DOM representation for downstream traversal.
json_domExtracted fields
Execute customer-defined CSS or XPath rules and return the selected content.
extract_rulesScreenshot
Capture the full page or a selected element and receive the image as base64.
screenshot- Need the page?
- Plain HTML or JSON DOM
- Need response context?
- JSON envelope
- Need named fields?
- Extraction rules
- Need visual evidence?
- Screenshot
Developer integration
Add browser-backed retrieval to the stack you already run.
Call the REST endpoint from your server, keep the API key out of client code, URL-encode request parameters, set a finite timeout, and handle non-success responses deliberately.
Request recipe
Start with one observable state.
These examples wait for main, scroll to it, and request a JSON response. Replace the target, selector, and actions with a sequence validated against your own eligible source.
- Endpoint
https://api.webscrapingapi.com/v1- Secret
WSA_API_KEYin server environment- Readiness
wait_for_css=main- Actions
- JSON-encode
js_instructions - Antwort
- Check status before parsing
: "${WSA_API_KEY:?Set WSA_API_KEY}"
ACTIONS='[{"action":"scrollTo","selector":"main","timeout":1000,"block":"start"}]'
curl --get --fail-with-body --max-time 120 \
"https://api.webscrapingapi.com/v1" \
--data-urlencode "api_key=$WSA_API_KEY" \
--data-urlencode "url=https://example.com/app" \
--data-urlencode "wait_for_css=main" \
--data-urlencode "js_instructions=$ACTIONS" \
--data-urlencode "json_response=1"import json
import os
import requests
api_key = os.getenv("WSA_API_KEY")
if not api_key:
raise RuntimeError("Set WSA_API_KEY")
response = requests.get(
"https://api.webscrapingapi.com/v1",
params={
"api_key": api_key,
"url": "https://example.com/app",
"wait_for_css": "main",
"js_instructions": json.dumps([{
"action": "scrollTo", "selector": "main",
"timeout": 1000, "block": "start"
}]),
"json_response": 1,
},
timeout=120,
)
response.raise_for_status()
print(response.json())const apiKey = process.env.WSA_API_KEY;
if (!apiKey) throw new Error("Set WSA_API_KEY");
const params = new URLSearchParams({
api_key: apiKey,
url: "https://example.com/app",
wait_for_css: "main",
js_instructions: JSON.stringify([{
action: "scrollTo", selector: "main",
timeout: 1000, block: "start"
}]),
json_response: "1",
});
const response = await fetch(
"https://api.webscrapingapi.com/v1?" + params,
{ signal: AbortSignal.timeout(120_000) }
);
if (!response.ok) throw new Error("API status " + response.status);
console.log(await response.json());<?php
$apiKey = getenv("WSA_API_KEY");
if (!$apiKey) throw new RuntimeException("Set WSA_API_KEY");
$actions = json_encode([[
"action" => "scrollTo", "selector" => "main",
"timeout" => 1000, "block" => "start",
]], JSON_THROW_ON_ERROR);
$query = http_build_query([
"api_key" => $apiKey,
"url" => "https://example.com/app",
"wait_for_css" => "main",
"js_instructions" => $actions,
"json_response" => 1,
]);
$client = curl_init("https://api.webscrapingapi.com/v1?" . $query);
curl_setopt_array($client, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($client);
$status = curl_getinfo($client, CURLINFO_RESPONSE_CODE);
$error = curl_error($client);
curl_close($client);
if ($body === false) throw new RuntimeException($error);
if ($status >= 400) throw new RuntimeException("API status " . $status);
echo $body;package main
import (
"fmt"
"io"
"net/http"
"net/url"
"os"
"time"
)
func main() {
apiKey := os.Getenv("WSA_API_KEY")
if apiKey == "" { panic("Set WSA_API_KEY") }
params := url.Values{}
params.Add("api_key", apiKey)
params.Add("url", "https://example.com/app")
params.Add("wait_for_css", "main")
params.Add("js_instructions", "[{\"action\":\"scrollTo\",\"selector\":\"main\",\"timeout\":1000,\"block\":\"start\"}]")
params.Add("json_response", "1")
client := &http.Client{Timeout: 120 * time.Second}
response, err := client.Get(
"https://api.webscrapingapi.com/v1?" + params.Encode(),
)
if err != nil { panic(err) }
defer response.Body.Close()
if response.StatusCode >= 400 {
panic(fmt.Sprintf("API status %d", response.StatusCode))
}
body, err := io.ReadAll(response.Body)
if err != nil { panic(err) }
fmt.Println(string(body))
}import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
public final class BrowserApiExample {
public static void main(String[] args) throws Exception {
var apiKey = System.getenv("WSA_API_KEY");
if (apiKey == null || apiKey.isBlank()) {
throw new IllegalStateException("Set WSA_API_KEY");
}
var actions = "[{\"action\":\"scrollTo\",\"selector\":\"main\"," +
"\"timeout\":1000,\"block\":\"start\"}]";
var query = "api_key=" + URLEncoder.encode(apiKey, StandardCharsets.UTF_8)
+ "&url=" + URLEncoder.encode("https://example.com/app", StandardCharsets.UTF_8)
+ "&wait_for_css=main"
+ "&js_instructions=" + URLEncoder.encode(actions, StandardCharsets.UTF_8)
+ "&json_response=1";
var request = HttpRequest.newBuilder()
.uri(URI.create("https://api.webscrapingapi.com/v1?" + query))
.timeout(Duration.ofSeconds(120)).GET().build();
var response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() >= 400) {
throw new RuntimeException("API status " + response.statusCode());
}
System.out.println(response.body());
}
}
using System.Net.Http;
var apiKey = Environment.GetEnvironmentVariable("WSA_API_KEY");
if (string.IsNullOrWhiteSpace(apiKey))
throw new InvalidOperationException("Set WSA_API_KEY");
var actions = "[{\"action\":\"scrollTo\",\"selector\":\"main\"," +
"\"timeout\":1000,\"block\":\"start\"}]";
var requestUrl = "https://api.webscrapingapi.com/v1?api_key="
+ Uri.EscapeDataString(apiKey)
+ "&url=" + Uri.EscapeDataString("https://example.com/app")
+ "&wait_for_css=main"
+ "&js_instructions=" + Uri.EscapeDataString(actions)
+ "&json_response=1";
using var client = new HttpClient {
Timeout = TimeSpan.FromSeconds(120)
};
var response = await client.GetAsync(requestUrl);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());require "json"
require "net/http"
require "uri"
api_key = ENV["WSA_API_KEY"]
raise "Set WSA_API_KEY" if api_key.nil? || api_key.empty?
uri = URI("https://api.webscrapingapi.com/v1")
uri.query = URI.encode_www_form(
api_key: api_key,
url: "https://example.com/app",
wait_for_css: "main",
js_instructions: [{
action: "scrollTo", selector: "main",
timeout: 1000, block: "start"
}].to_json,
json_response: 1
)
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.open_timeout = 10
http.read_timeout = 120
response = http.get(uri.request_uri)
raise "API status #{response.code}" unless response.is_a?(Net::HTTPSuccess)
puts response.bodyOperating ownership
We operate browser execution.
Your team owns the intended state.
A clear boundary makes evaluation more realistic: infrastructure moves behind the API, while source eligibility and business correctness stay with the customer.
WebScrapingAPI
Hosted browser request execution
- REST request validation and execution
- Hosted browser runtime with JavaScript rendering
- Proxy geolocation, IP rotation, and IP block handling
- Documented waits and instruction execution
- Requested output generation and response delivery
- Documented API error response
Ihr Team von Experten
Source and data-product decisions
- Target eligibility, purpose, and request policy
- Request configuration, interactions, and readiness conditions
- Selectors, extraction schema, and response validation
- Source-change maintenance and regression tests
- Scheduling, storage, retention, and downstream use
Page stateCustomer specifies the state; WebScrapingAPI runs the documented waits and actions.
Browser runtimeWebScrapingAPI operates hosted browser execution and the request infrastructure behind it.
AntwortWebScrapingAPI returns the selected output or error; the customer validates business completeness.
ExtractionWebScrapingAPI executes supplied rules; the customer maintains selectors, schema, and quality checks.
Use Browser API only for eligible public pages. Review source terms, applicable requirements, and the Servicevereinbarung für Kunden, then apply appropriate access, retention, and data-use policies.
Use cases
Use Browser API where rendered state changes the answer.
Browser API supplies the controlled page capture. Your downstream system turns that response into an observation, alert, test result, record, or evidence item.
Product choice
Choose the operating boundary
your workload needs.
Browser API is a request-based browser execution product. It does not expose a live browser-control connection and does not replace a fully managed data-delivery program.
Netzstrecke
Proxies
Infrastructure building blockManaged RetrievalYour team runs the HTTP client, browser or parser, retry policy, validation, and storage.
Scraper-API
One page retrievalGeführte BrowseranfrageSend a URL for a managed page request with optional rendering and documented response formats.
Browser-API
Rendered state and interactionGuided evaluationDefine readiness, supported actions, context, and output in one server-side REST request.
Crawl-API
Scoped multi-page collectionOperated deliveryPlan a bounded collection when the unit of work spans related eligible pages rather than one browser request.
Verwaltete Daten
Data delivered to specificationDefinition von Quellen, Schema, Kadenz, Qualität und Bestimmung, während WebScrapingAPI das wiederkehrende Programm betreibt.
Pricing orientation
Evaluate the actual page states
your production workload needs.
Current pricing is the source of truth. A useful evaluation measures representative targets, waits, actions, outputs, errors, and timeouts—not a generic request count alone.
Prove one stable request recipe.
Start with a representative dynamic page, then validate the smallest combination of context, readiness, actions, and output that meets your requirements.
- Representative eligible target set
- Observable readiness condition
- Shortest required interaction sequence
- Output and business-validation contract
FAQ
Browser API questions for a grounded evaluation.
Confirm the product boundary first, then use the current documentation for parameter values, action syntax, and error handling.
What is Browser API?
Browser API is a server-side REST request that loads an eligible public webpage in a hosted browser, applies documented waits and actions, and returns the selected response to your application.
When should I use Browser API?
Use Browser API when the target depends on client-side JavaScript, a particular rendered state, or a guided sequence such as clicking, scrolling, typing, selecting, or submitting before capture.
What can Browser API return?
The documented output choices include raw HTML, a JSON envelope, a JSON DOM representation, customer-defined extracted fields, and a screenshot returned as base64 inside the response.
Which page actions are supported?
Documented JavaScript instructions include click, click and navigate, scrolling, typed values, value assignment, selection, submission, focus, and waits. Build and test the shortest sequence that reaches the state you need.
How can a request wait for the right page state?
Use a documented page lifecycle value, a delay, or a CSS selector. You can combine wait_until, wait_for, wait_for_css, and instruction-level waits according to the target behavior.
Can I control device, viewport, and location context?
Yes. Documented controls include desktop, mobile, or tablet device context; window width and height; and supported country-level request context.
Can Browser API capture screenshots?
Yes. Request a screenshot and use documented screenshot options for full-page or selector capture and output dimensions. Screenshot content is returned as base64 in the response.
Does Browser API expose a live browser-control connection?
No. Browser API uses a request-response REST interface. Your application declares supported waits, actions, context, and output through request parameters, then receives the selected response or an API error.
Who owns interaction instructions and extraction rules?
WebScrapingAPI runs hosted browser execution and returns the requested output. Your team owns target eligibility, interaction instructions, selectors, extraction schema, content validation, and source-change maintenance.
How is Browser API different from Scraper API and Managed Data?
Scraper API fits a managed page retrieval with optional rendering. Browser API adds explicit page-state and interaction controls to one REST request. Managed Data moves recurring collection, extraction, quality, and delivery into an operated program.
Your first browser request
Turn one dynamic page into a repeatable request.
Start self-serve, or bring us the target behavior, context, required state, output, and expected request profile for a production review.