Web Unblocker API

The Web Unblocker API is designed to retrieve page content from a target URL as it appears in a specific country or region. You simply submit the target URL and a few control parameters; our system handles proxying, unblocking, optional rendering, page loading, and returning the results.

This API is suitable for accessing public web pages that employ basic anti-scraping measures, exhibit geo-specific content, or require a stable scraping pipeline.

Scraping data that requires logging in often involves accessing personal or sensitive information—practices explicitly prohibited by many websites in their terms of service.

To help you comply with target website policies and avoid potential legal issues, we focus on providing tools that scrape only publicly available data.

The Web Unblocker API prioritizes availability and stability and does not currently offer complex structured data extraction capabilities. Services with extraction features will be launched in the future; please contact us if you require custom data cleaning services.

API Endpoint #

POST /v1/web-unblocker/query

Authentication #

Requests must include an API Key.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Response Headers #

A trace ID is returned with every request; it is recommended to log this on the client side to facilitate troubleshooting.

X-Request-Id: request-id

Request Parameters #

Parameter	Type	Required	Default	Description
target_url	string	Yes	–	The target webpage URL; must be a valid http or https address.
js_render	integer	No	0	Whether to enable JavaScript rendering. Supported values: 0 = disabled, 1 = enabled.
format	array	No	["html"]	An array of response formats. Valid element values: html, png.
country	string	No	–	The two-letter uppercase country/region code used when accessing the target webpage (e.g., US).

If omitted or left empty, no specific country/region is selected.headersobjectNo–Request headers to be passed through to the target webpage; must be string key-value pairs.cookiesobjectNo–Cookies to be passed through to the target webpage; must be string key-value pairs.

Parameter Description #

target_url

target_url is the address of the target webpage to be scraped.

Example:

{
"target_url": "https://example.com"
}

Requirements:

• Must start with http:// or https://.
• Must contain a valid host.
• Internal network addresses, local addresses, and invalid URLs are not supported.
• It is recommended to provide the final page URL to avoid excessive redirects, which can impact stability and response time.

country

The country parameter specifies the exit country or region to use when accessing the target website.

Example:

{
"country": "US"
}

It is recommended to explicitly provide this parameter if the target website exhibits significant regional variations. If the parameter is omitted or left empty, no specific country or region is selected, and the system processes the request according to its default policy.

js_render

The js_render parameter controls whether JavaScript rendering is enabled.

Example:

{
"js_render": 1
}

Value description:

Value	Description
1	Enable JavaScript rendering.
0	Disable JavaScript rendering.

If the target page is standard static HTML, it is recommended to omit this parameter or set it to 0 for faster response times.

It is recommended to enable this only in the following scenarios:

• The main page content is dynamically generated via JavaScript.
• Valid content cannot be retrieved by requesting the HTML directly.
• The target page displays content only after frontend API calls have loaded.
• A png screenshot is required.

format

The format parameter specifies the format of the returned content; its type is an array of strings.

Available values:

Array Element	Description
html	Returns the unlocked raw HTML content.
png	Returns a screenshot of the target page.

Example:

{
"format": ["html"]
}

If you need to return both HTML and a screenshot, you can pass:

{
"format": ["html", "png"]
}

When format includes png, you must also enable js_render=1. If the combination of request parameters does not meet the requirements, the API will return an error indicating that the request conditions were not met.

headers

headers is used to pass request headers through to the target webpage.

Example:

{
"headers": {
"User-Agent": "Mozilla/5.0",
"Accept-Language": "en-US,en;q=0.9"
}
}

Parameter requirements:

• Must be an object.
• Keys must not be empty after trimming leading and trailing whitespace.
• Values ​​must be strings.
• An empty object {} is valid.

Do not pass request headers containing sensitive credentials unless you explicitly know the target website requires this information.

cookies

cookies is used to pass cookies through to the target webpage.

Example:

{
"cookies": {
"session_id": "example-session"
}
}

Requirements:

• Must be an object.
• Keys must not be empty after trimming leading and trailing whitespace.
• Values ​​must be strings.
• An empty object {} is valid.

Exercise caution when passing cookies; avoid using account credentials, login states, or other sensitive information with untrusted target websites.

Request Example #

Minimal Request

curl -X POST "https://api.example.com/v1/web-unblocker/query" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"target_url": "https://example.com"
}'

Successful Response #

Upon success, the API returns a standardized JSON structure.

format = [“html”]

{
"code": 200,
"message": "success",
"data": {
"html": "<!doctype html><html>...</html>",
"http_status": 200
}
}

format = [“png”]

{
"code": 200,
"message": "success",
"data": {
"image": "base64-image-content",
"http_status": 200
}
}

Field descriptions:

Field	Type	Description
html	string	Returned when format includes html; the unlocked raw HTML content.
image	string	Returned when format includes png; the Base64 content of the target page’s PNG screenshot.
http_status	integer	The HTTP status code of the target page.

Response fields are returned based on the requested format array; fields for formats that were not requested will not appear in the response.

Public responses do not return account information, keys, or other sensitive data.

Failure Response #

Upon failure, the API returns a standardized error structure. The HTTP status code for business-level failures is fixed at 200; please use the code field in the response body to determine whether the request was successful.

{
"code": 120404,
"message": "Request timed out. Please increase the timeout or retry later.",
"data": null
}

Common error codes:

code	Description
100001	Service temporarily unavailable; please retry later.
100301	Invalid request parameters (e.g., missing target_url, malformed URL, await_ms out of range, invalid js_render or format type, or invalid element selection value).
110102	API Key is missing, malformed, invalid, or has been rotated.
110103	API Key has been deactivated.
110104	API Key status is abnormal; please refresh and retry.
110205	Subscription plan status is abnormal; please refresh and retry.
110301	Insufficient balance to initiate this request.

120401The request failed pre-execution validation (e.g., the target URL is inaccessible, or the user’s QPS limit has been exceeded).120402The service is currently busy due to a high number of concurrent connections; please contact customer support to adjust your connection node or try again later.120403The crawler request failed to execute.120404Request execution timed out.120405The service is temporarily unavailable; please try again later.120406The provided parameter value is not currently supported (e.g., a specific country, format, or await_ms value is not supported).120407The parameter combination is not currently supported.120408Request conditions were not met (e.g., format is set to png, but the necessary rendering capability is not enabled).

For more detailed information on responses, please refer to the “Response Codes” section.