API Documentation

Everything you need to integrate WebScraping.AI into your applications.

Quick Start

Get started with WebScraping.AI in under 5 minutes. Here's a simple example to extract data from any webpage.

1
Get your API key

Sign up at webscraping.ai to get your free API key with 2,000 credits.

2
Make your first request

Try the AI question endpoint to ask a question about any webpage:

cURL
curl -G "https://api.webscraping.ai/ai/question" \
  --data-urlencode "api_key=YOUR_API_KEY" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "question=What is this page about?"
Python
import requests

response = requests.get("https://api.webscraping.ai/ai/question", params={
    "api_key": "YOUR_API_KEY",
    "url": "https://example.com",
    "question": "What is this page about?"
})

print(response.text)
JavaScript
const params = new URLSearchParams({
  api_key: 'YOUR_API_KEY',
  url: 'https://example.com',
  question: 'What is this page about?'
});

const response = await fetch(
  `https://api.webscraping.ai/ai/question?${params}`
);
const answer = await response.text();
console.log(answer);
PHP
$params = http_build_query([
    'api_key' => 'YOUR_API_KEY',
    'url' => 'https://example.com',
    'question' => 'What is this page about?'
]);

$response = file_get_contents(
    "https://api.webscraping.ai/ai/question?{$params}"
);

echo $response;
Ruby
require 'net/http'
require 'uri'

params = {
  api_key: 'YOUR_API_KEY',
  url: 'https://example.com',
  question: 'What is this page about?'
}

uri = URI('https://api.webscraping.ai/ai/question')
uri.query = URI.encode_www_form(params)

response = Net::HTTP.get(uri)
puts response
3
Get your response

The API returns the AI-generated answer as plain text:

This page is the example domain maintained by IANA for illustrative purposes in documents and tutorials.
That's it! You've made your first API call. Each request costs 1 credit (AI endpoints cost 5 credits). Failed requests are free.

Authentication

All API requests require an API key. Pass your key as a query parameter:

HTTP
GET https://api.webscraping.ai/html?url=https://example.com&api_key=YOUR_API_KEY
Keep your API key secure! Don't expose it in client-side code. Use environment variables or a backend proxy for production applications.

Base URL

All API endpoints use this base URL:

https://api.webscraping.ai

Rules & Pricing

  • Each request costs 1 credit. AI endpoints cost 5 credits. JS rendering and residential proxies have different pricing.
  • Requests can take up to 30 seconds. Use the timeout parameter to control duration.
  • Failed requests are free. You're only charged for successful responses.
Credit Cost Summary
Configuration Credits Notes
Basic (no JS, datacenter proxy) 1 Fastest, for static sites
With JS rendering 2 Default setting, headless Chrome
Residential proxy (no JS) 5 For anti-bot protected sites
Residential proxy + JS 10 Maximum compatibility
AI endpoints (/ai/question, /ai/fields) 5 Per request, plus proxy costs

All costs are per successful request. Failed requests are free.

Success Rates & Retrying

Our API typically achieves 80%+ success rate for most websites. If you encounter failures:

  • Retry the request - Many failures are temporary due to network issues or website load
  • Increase timeout - Set timeout to 20000-30000ms for slow-loading websites
  • Use residential proxies - Set proxy=residential if datacenter proxies are blocked
  • Adjust js_timeout - Increase js_timeout for pages with slow-loading dynamic content

Best Practices

JavaScript Rendering

JS rendering is enabled by default (js=true) using headless Chrome. Keep enabled for SPAs (React, Vue, Angular), AJAX content, and dynamic pages. Disable (js=false) for static sites, faster responses, or server-rendered content.

Proxy Strategy

Start with datacenter proxies (default) for speed and cost. Switch to residential proxies if: website blocks datacenter IPs, getting 403 errors, need to bypass anti-bot protection, or scraping geo-restricted content.

Sending Cookies

Send cookies to the target website using the headers parameter. Cookies should be formatted as a standard Cookie header value with semicolon-separated key-value pairs.

Cookie Format
Format
"Cookie": "key1=value1; key2=value2; key3=value3"
Example
curl -G "https://api.webscraping.ai/html" \
  --data-urlencode "api_key=YOUR_API_KEY" \
  --data-urlencode "url=https://example.com/dashboard" \
  --data-urlencode 'headers={"Cookie":"session_id=abc123; user_pref=dark_mode; lang=en"}'
import requests
import json

response = requests.get("https://api.webscraping.ai/html", params={
    "api_key": "YOUR_API_KEY",
    "url": "https://example.com/dashboard",
    "headers": json.dumps({
        "Cookie": "session_id=abc123; user_pref=dark_mode; lang=en"
    })
})
print(response.text)
const params = new URLSearchParams({
  api_key: 'YOUR_API_KEY',
  url: 'https://example.com/dashboard',
  headers: JSON.stringify({
    Cookie: 'session_id=abc123; user_pref=dark_mode; lang=en'
  })
});
const response = await fetch(`https://api.webscraping.ai/html?${params}`);
console.log(await response.text());
$params = http_build_query([
    'api_key' => 'YOUR_API_KEY',
    'url' => 'https://example.com/dashboard',
    'headers' => json_encode([
        'Cookie' => 'session_id=abc123; user_pref=dark_mode; lang=en'
    ])
]);
$html = file_get_contents("https://api.webscraping.ai/html?{$params}");
echo $html;
require 'net/http'
require 'json'
params = {
  api_key: 'YOUR_API_KEY',
  url: 'https://example.com/dashboard',
  headers: { Cookie: 'session_id=abc123; user_pref=dark_mode; lang=en' }.to_json
}
uri = URI('https://api.webscraping.ai/html')
uri.query = URI.encode_www_form(params)
puts Net::HTTP.get(uri)
Common use cases: Session authentication, user preferences, A/B testing variants, geo-location settings, and accessing logged-in content.

Official SDKs

Use our official SDKs for easier integration in your preferred language.

Need an SDK for another language? Let us know!

Using with AI Tools

Integrate WebScraping.AI with AI assistants and LLM platforms.

MCP Server

Our open-source MCP server integrates WebScraping.AI directly with AI assistants that support the Model Context Protocol:

  • Claude Desktop
  • Cursor
  • Windsurf
  • Any MCP-compatible platform
OpenAPI Specification

Use our OpenAPI specification to integrate with AI tools that support API schemas, such as GPT Actions or custom agents.

Proxy Mode

Use WebScraping.AI as a proxy server for your existing tools. Route requests through our infrastructure without changing your code.

Proxy Settings
Host proxy.webscraping.ai
Port 8888
Username Your API key
Password Parameters (e.g., js=true&proxy=residential)
Example
curl -x "http://YOUR_API_KEY:js=true&proxy=residential@proxy.webscraping.ai:8888" \
  -k "https://example.com"
import requests

proxy_url = "http://YOUR_API_KEY:js=true&proxy=residential@proxy.webscraping.ai:8888"

response = requests.get(
    "https://example.com",
    proxies={"http": proxy_url, "https": proxy_url},
    verify=False  # Required for self-signed certificate
)
print(response.text)
const HttpsProxyAgent = require('https-proxy-agent');

const proxyUrl = 'http://YOUR_API_KEY:js=true&proxy=residential@proxy.webscraping.ai:8888';
const agent = new HttpsProxyAgent(proxyUrl);

const response = await fetch('https://example.com', {
  agent,
  rejectUnauthorized: false
});
console.log(await response.text());
$ch = curl_init('https://example.com');
curl_setopt($ch, CURLOPT_PROXY, 'proxy.webscraping.ai:8888');
curl_setopt($ch, CURLOPT_PROXYUSERPWD, 'YOUR_API_KEY:js=true&proxy=residential');
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
echo $response;
require 'net/http'
proxy = Net::HTTP::Proxy('proxy.webscraping.ai', 8888, 'YOUR_API_KEY', 'js=true&proxy=residential')
uri = URI('https://example.com')
response = proxy.start(uri.host, uri.port, use_ssl: true, verify_mode: OpenSSL::SSL::VERIFY_NONE) do |http|
  http.get(uri)
end
puts response.body
Note: Proxy mode uses a self-signed SSL certificate. Use -k flag in cURL or verify=False in Python.

AI Endpoints

Ask Questions About a Page

Use AI to answer questions about any webpage. Perfect for extracting specific information without parsing HTML.

GET /ai/question
Parameters → All parameters reference
Parameter Type Description
url required string URL of the webpage to analyze
question required string Question to ask about the page content
api_key required string Your API key
Example
curl -G "https://api.webscraping.ai/ai/question" \
  --data-urlencode "api_key=YOUR_API_KEY" \
  --data-urlencode "url=https://news.ycombinator.com" \
  --data-urlencode "question=What are the top 3 stories on this page?"
import requests

response = requests.get("https://api.webscraping.ai/ai/question", params={
    "api_key": "YOUR_API_KEY",
    "url": "https://news.ycombinator.com",
    "question": "What are the top 3 stories on this page?"
})
print(response.text)
const params = new URLSearchParams({
  api_key: 'YOUR_API_KEY',
  url: 'https://news.ycombinator.com',
  question: 'What are the top 3 stories on this page?'
});
const response = await fetch(`https://api.webscraping.ai/ai/question?${params}`);
console.log(await response.text());
$params = http_build_query([
    'api_key' => 'YOUR_API_KEY',
    'url' => 'https://news.ycombinator.com',
    'question' => 'What are the top 3 stories on this page?'
]);
$response = file_get_contents("https://api.webscraping.ai/ai/question?{$params}");
echo $response;
require 'net/http'
params = { api_key: 'YOUR_API_KEY', url: 'https://news.ycombinator.com', question: 'What are the top 3 stories on this page?' }
uri = URI('https://api.webscraping.ai/ai/question')
uri.query = URI.encode_www_form(params)
puts Net::HTTP.get(uri)
Response
The top 3 stories on Hacker News are: 1. "Show HN: I built an AI-powered code review tool" 2. "The future of web development" 3. "Why Rust is taking over systems programming"

Extract Structured Fields

Extract specific data fields from any webpage as structured JSON. Ideal for scraping product details, articles, profiles, and more.

GET /ai/fields
Parameters → All parameters reference
Parameter Type Description
url required string URL of the webpage to extract from
fields required object Object with field names as keys and extraction instructions as values
api_key required string Your API key
Example - Extract Product Data
curl -G "https://api.webscraping.ai/ai/fields" \
  --data-urlencode "api_key=YOUR_API_KEY" \
  --data-urlencode "url=https://amazon.com/dp/B08N5WRWNW" \
  --data-urlencode "fields[title]=Product title" \
  --data-urlencode "fields[price]=Current price with currency" \
  --data-urlencode "fields[rating]=Average star rating"
import requests

response = requests.get("https://api.webscraping.ai/ai/fields", params={
    "api_key": "YOUR_API_KEY",
    "url": "https://amazon.com/dp/B08N5WRWNW",
    "fields[title]": "Product title",
    "fields[price]": "Current price with currency",
    "fields[rating]": "Average star rating"
})
print(response.json())
const params = new URLSearchParams({
  api_key: 'YOUR_API_KEY',
  url: 'https://amazon.com/dp/B08N5WRWNW',
  'fields[title]': 'Product title',
  'fields[price]': 'Current price with currency',
  'fields[rating]': 'Average star rating'
});
const response = await fetch(`https://api.webscraping.ai/ai/fields?${params}`);
console.log(await response.json());
$params = http_build_query([
    'api_key' => 'YOUR_API_KEY',
    'url' => 'https://amazon.com/dp/B08N5WRWNW',
    'fields' => ['title' => 'Product title', 'price' => 'Current price with currency', 'rating' => 'Average star rating']
]);
$response = file_get_contents("https://api.webscraping.ai/ai/fields?{$params}");
print_r(json_decode($response, true));
require 'net/http'
require 'json'
params = { api_key: 'YOUR_API_KEY', url: 'https://amazon.com/dp/B08N5WRWNW', 'fields[title]' => 'Product title', 'fields[price]' => 'Current price with currency' }
uri = URI('https://api.webscraping.ai/ai/fields')
uri.query = URI.encode_www_form(params)
puts JSON.parse(Net::HTTP.get(uri))
Response
{ "title": "Apple AirPods Pro (2nd Generation)", "price": "$249.00", "rating": "4.7 out of 5 stars", "reviews_count": "125,432", "availability": "In Stock" }
Pro tip: Be specific with your field descriptions. Instead of "price", use "Current sale price including currency symbol" for better accuracy.

Scraping Endpoints

Get Page HTML

Fetch the full HTML content of any webpage. Includes JavaScript rendering via headless Chrome and automatic proxy rotation.

GET /html
Parameters → All parameters reference
Parameter Type Description
url required string URL of the webpage to fetch
api_key required string Your API key
js optional boolean Enable JavaScript rendering (default: true)
proxy optional string Proxy type: "datacenter" (default) or "residential"
Example
curl -G "https://api.webscraping.ai/html" \
  --data-urlencode "api_key=YOUR_API_KEY" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "js=true"
import requests

response = requests.get("https://api.webscraping.ai/html", params={
    "api_key": "YOUR_API_KEY",
    "url": "https://example.com",
    "js": "true"
})
print(response.text)
const params = new URLSearchParams({
  api_key: 'YOUR_API_KEY',
  url: 'https://example.com',
  js: 'true'
});
const response = await fetch(`https://api.webscraping.ai/html?${params}`);
console.log(await response.text());
$params = http_build_query([
    'api_key' => 'YOUR_API_KEY',
    'url' => 'https://example.com',
    'js' => 'true'
]);
$html = file_get_contents("https://api.webscraping.ai/html?{$params}");
echo $html;
require 'net/http'
params = { api_key: 'YOUR_API_KEY', url: 'https://example.com', js: 'true' }
uri = URI('https://api.webscraping.ai/html')
uri.query = URI.encode_www_form(params)
puts Net::HTTP.get(uri)
POST /html

Use POST requests to send data to the target page (e.g., form submissions, API calls).

Additional POST Parameters
body optional string Request body to send to the target URL
POST Example
# Submit form data to a target page
curl -X POST "https://api.webscraping.ai/html" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "api_key=YOUR_API_KEY" \
  -d "url=https://httpbin.org/post" \
  -d "body=username=test&password=demo"
import requests

# Submit form data to a target page
response = requests.post("https://api.webscraping.ai/html", data={
    "api_key": "YOUR_API_KEY",
    "url": "https://httpbin.org/post",
    "body": "username=test&password=demo"
})
print(response.text)
const response = await fetch('https://api.webscraping.ai/html', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    api_key: 'YOUR_API_KEY',
    url: 'https://httpbin.org/post',
    body: 'username=test&password=demo'
  })
});
console.log(await response.text());
Use cases: Login to websites, submit search forms, interact with APIs that require POST requests, or scrape pages that need form submissions.

Get Page Text

Extract only the visible text content from a webpage. Perfect for feeding content to LLMs or text analysis.

GET /text
Parameters → All parameters reference
Parameter Type Description
url required string URL of the webpage
text_format optional string "plain" (default), "json", or "xml"
return_links optional boolean Include links in JSON response (default: false)
Example with JSON format
curl -G "https://api.webscraping.ai/text" \
  --data-urlencode "api_key=YOUR_API_KEY" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "text_format=json"
import requests

response = requests.get("https://api.webscraping.ai/text", params={
    "api_key": "YOUR_API_KEY",
    "url": "https://example.com",
    "text_format": "json"
})
print(response.json())
const params = new URLSearchParams({
  api_key: 'YOUR_API_KEY',
  url: 'https://example.com',
  text_format: 'json'
});
const response = await fetch(`https://api.webscraping.ai/text?${params}`);
console.log(await response.json());
$params = http_build_query([
    'api_key' => 'YOUR_API_KEY',
    'url' => 'https://example.com',
    'text_format' => 'json'
]);
$response = file_get_contents("https://api.webscraping.ai/text?{$params}");
print_r(json_decode($response, true));
require 'net/http'
require 'json'
params = { api_key: 'YOUR_API_KEY', url: 'https://example.com', text_format: 'json' }
uri = URI('https://api.webscraping.ai/text')
uri.query = URI.encode_www_form(params)
puts JSON.parse(Net::HTTP.get(uri))
Response
{ "title": "Example Domain", "description": "This domain is for use in illustrative examples...", "content": "Example Domain\n\nThis domain is for use in illustrative examples in documents..." }

Get Selected HTML

Extract HTML from specific page elements using CSS selectors. Useful when you only need a portion of the page.

GET /selected
Parameters → All parameters reference
Parameter Type Description
url required string URL of the webpage
selector required string CSS selector (e.g., "h1", ".price", "#main")
Example
curl -G "https://api.webscraping.ai/selected" \
  --data-urlencode "api_key=YOUR_API_KEY" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "selector=h1"
import requests

response = requests.get("https://api.webscraping.ai/selected", params={
    "api_key": "YOUR_API_KEY",
    "url": "https://example.com",
    "selector": "h1"
})
print(response.text)
const params = new URLSearchParams({
  api_key: 'YOUR_API_KEY',
  url: 'https://example.com',
  selector: 'h1'
});
const response = await fetch(`https://api.webscraping.ai/selected?${params}`);
console.log(await response.text());
$params = http_build_query([
    'api_key' => 'YOUR_API_KEY',
    'url' => 'https://example.com',
    'selector' => 'h1'
]);
$html = file_get_contents("https://api.webscraping.ai/selected?{$params}");
echo $html;
require 'net/http'
params = { api_key: 'YOUR_API_KEY', url: 'https://example.com', selector: 'h1' }
uri = URI('https://api.webscraping.ai/selected')
uri.query = URI.encode_www_form(params)
puts Net::HTTP.get(uri)
Response
<h1>Example Domain</h1>
Multiple selectors? Use /selected-multiple endpoint with a selectors[] array parameter to extract multiple elements in one request.

Account Information

Check your remaining API credits and account status.

GET /account
Example
curl "https://api.webscraping.ai/account?api_key=YOUR_API_KEY"
import requests

response = requests.get("https://api.webscraping.ai/account", params={
    "api_key": "YOUR_API_KEY"
})
print(response.json())
const response = await fetch(
  'https://api.webscraping.ai/account?api_key=YOUR_API_KEY'
);
console.log(await response.json());
$response = file_get_contents(
    "https://api.webscraping.ai/account?api_key=YOUR_API_KEY"
);
print_r(json_decode($response, true));
require 'net/http'
require 'json'
uri = URI('https://api.webscraping.ai/account?api_key=YOUR_API_KEY')
puts JSON.parse(Net::HTTP.get(uri))
Response
{ "email": "user@example.com", "remaining_api_calls": 1850, "resets_at": 1704067200, "remaining_concurrency": 10 }

Response Headers

Every successful API response includes helpful headers with request metadata.

Header Description Example
X-Credits-Used Number of credits consumed by this request 2
X-Credits-Remaining Your remaining credit balance 1850
X-Target-Status HTTP status code from the target website 200
X-Target-Url Final URL after redirects (if any) https://example.com/page
Content-Type Response content type text/html; charset=utf-8
Reading Response Headers
# Use -i flag to include headers in output
curl -i "https://api.webscraping.ai/html?api_key=YOUR_API_KEY&url=https://example.com"

# Response includes:
# X-Credits-Used: 2
# X-Credits-Remaining: 1850
# X-Target-Status: 200
import requests

response = requests.get("https://api.webscraping.ai/html", params={
    "api_key": "YOUR_API_KEY",
    "url": "https://example.com"
})

# Access response headers
credits_used = response.headers.get('X-Credits-Used')
credits_remaining = response.headers.get('X-Credits-Remaining')
target_status = response.headers.get('X-Target-Status')

print(f"Credits used: {credits_used}")
print(f"Credits remaining: {credits_remaining}")
const response = await fetch(
  'https://api.webscraping.ai/html?api_key=YOUR_API_KEY&url=https://example.com'
);

// Access response headers
const creditsUsed = response.headers.get('X-Credits-Used');
const creditsRemaining = response.headers.get('X-Credits-Remaining');
const targetStatus = response.headers.get('X-Target-Status');

console.log(`Credits used: ${creditsUsed}`);
Pro tip: Use X-Credits-Remaining to monitor your quota and implement alerts when credits are running low.

Error Codes

Understanding API error responses and how to handle them.

Code Description Solution
400 Invalid parameters Check parameter values and format
402 Insufficient credits Upgrade your plan or wait for credit reset
403 Invalid API key Verify your API key is correct
429 Too many concurrent requests Reduce request rate or upgrade for higher concurrency
500 Target website error Try again or check if target site is available
504 Request timeout Increase timeout parameter value
Good news: Failed requests don't count against your credit quota. You only pay for successful responses.

Parameters Reference

Complete documentation for all API parameters. Click on any parameter to see detailed information and examples.

Quick Reference
Parameter Type Default Description
url string required Target webpage URL
api_key string required Your API key for authentication
js boolean true Enable JavaScript rendering
js_timeout integer 2000 JavaScript rendering timeout (ms)
timeout integer 10000 Total request timeout (ms)
wait_for string - CSS selector to wait for
proxy string datacenter Proxy type
country string us Proxy country
device string desktop Device emulation
headers object - Custom HTTP headers
js_script string - Custom JavaScript to execute
custom_proxy string - Your own proxy URL
error_on_404 boolean false Return error for 404 pages
error_on_redirect boolean false Return error on redirects
url string required

The URL of the target webpage to scrape or analyze. Must be a valid HTTP or HTTPS URL.

Details
  • Must include protocol (http:// or https://)
  • URL encoding is handled automatically
  • Redirects are followed by default
  • Query parameters in URL are preserved
Example url=https://example.com/page?id=123
api_key string required

Your unique API key for authentication. Get your key from the dashboard.

Security: Never expose your API key in client-side code. Use environment variables or a backend proxy for production.
js boolean default: true

Enable JavaScript rendering using a headless Chromium browser. Required for SPAs, dynamic content, and modern web applications.

When to use js=true
  • Single Page Applications (React, Vue, Angular)
  • Content loaded via AJAX/fetch
  • Lazy-loaded images and content
  • Interactive elements that need to render
When to use js=false
  • Static HTML pages
  • Faster response times needed
  • Lower credit cost (no JS = 1 credit vs 2 credits)
  • Server-rendered content
Example
# With JS rendering (default)
curl "https://api.webscraping.ai/html?api_key=KEY&url=https://spa-app.com&js=true"

# Without JS rendering (faster, cheaper)
curl "https://api.webscraping.ai/html?api_key=KEY&url=https://static-site.com&js=false"
js_timeout integer default: 2000

Maximum time in milliseconds to wait for JavaScript execution after the page loads. Increase this value if you see loading indicators instead of actual content.

Details
  • Minimum: 1 ms
  • Maximum: 20000 ms (20 seconds)
  • Default: 2000 ms (2 seconds)
  • Only applies when js=true
Recommendations
  • Fast sites: 1000-2000 ms
  • Medium sites: 3000-5000 ms
  • Slow/heavy sites: 5000-10000 ms
  • Use wait_for for more precision
timeout integer default: 10000

Maximum total time in milliseconds for the entire request, including page retrieval, JavaScript rendering, and processing.

Details
  • Minimum: 1 ms
  • Maximum: 30000 ms (30 seconds)
  • Default: 10000 ms (10 seconds)
  • Increase if you get 504 timeout errors
Example timeout=15000

Sets a 15-second timeout for slow-loading pages

wait_for string optional

CSS selector to wait for before returning the page content. The request will wait until this element appears in the DOM, then return the content. This overrides js_timeout.

Use cases
  • Wait for product data to load
  • Wait for search results
  • Wait for lazy-loaded content
  • Wait for specific components to render
Examples
  • wait_for=.product-price
  • wait_for=#search-results
  • wait_for=[data-loaded="true"]
  • wait_for=.reviews-container
Example
# Wait for product grid to load before scraping
curl -G "https://api.webscraping.ai/html" \
  --data-urlencode "api_key=YOUR_API_KEY" \
  --data-urlencode "url=https://shop.com/products" \
  --data-urlencode "wait_for=.product-grid"
proxy string default: datacenter

Type of proxy to use for the request. Choose based on your target website's anti-bot measures.

Value Description Best for Cost
datacenter Fast datacenter proxies with rotating IPs Most websites, APIs, general scraping 1 credit
residential Real residential IPs from ISPs Anti-bot protected sites, sneaker sites, social media 5 credits
Tip: Start with datacenter proxies. Only switch to residential if you encounter blocks or CAPTCHAs.
country string default: us

Country code for geo-targeting. The request will be made from a proxy in the specified country.

Code Country Code Country
us United States ru Russia
gb United Kingdom jp Japan
de Germany kr South Korea
fr France in India
ca Canada it Italy
es Spain
Example
# Scrape from a UK IP address
curl "https://api.webscraping.ai/html?api_key=KEY&url=https://uk-shop.com&country=gb"
device string default: desktop

Device type emulation. Affects viewport size, user agent, and touch capabilities.

Value Viewport Use case
desktop 1920x1080 Desktop websites, full layouts
mobile 375x812 (iPhone X) Mobile sites, responsive layouts, AMP pages
tablet 768x1024 (iPad) Tablet-optimized layouts
headers object optional

Custom HTTP headers to send with the request. Useful for authentication, cookies, or custom user agents.

Format options
  • JSON object: headers={"Cookie":"session=abc"}
  • Nested params: headers[Cookie]=session=abc
Common headers
  • Cookie - Session cookies
  • Authorization - Bearer tokens
  • Referer - Referrer URL
Example
# Pass custom headers as JSON
curl -G "https://api.webscraping.ai/html" \
  --data-urlencode "api_key=YOUR_API_KEY" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode 'headers={"Cookie":"session=abc123","Authorization":"Bearer token"}'
js_script string optional

Custom JavaScript code to execute on the page after it loads. Useful for clicking buttons, scrolling, filling forms, or extracting data.

Use cases
  • Click "Load More" buttons
  • Scroll to load lazy content
  • Accept cookie banners
  • Fill and submit forms
  • Extract data from JavaScript variables
Tip: Use return_script_result=true to get the return value of your script instead of the page HTML.
Examples
# Click a button
js_script=document.querySelector('.load-more-btn').click()

# Scroll to bottom
js_script=window.scrollTo(0, document.body.scrollHeight)

# Extract data and return it
js_script=return JSON.stringify(window.__INITIAL_DATA__)
custom_proxy string optional

Use your own proxy server instead of our built-in proxy pool. Useful if you have specific proxy requirements or existing proxy subscriptions.

Format http://username:password@host:port Example custom_proxy=http://user:pass@proxy.example.com:8080
Recommended providers: Smartproxy, Bright Data
error_on_404 boolean default: false

Return an error response when the target page returns a 404 status code, instead of returning the 404 page content.

  • false (default): Returns the 404 page HTML content. Useful if you need to scrape the error page.
  • true: Returns a 500 error. Useful for validation or when you want failed pages to trigger error handling.
error_on_redirect boolean default: false

Return an error when the target page redirects, instead of following the redirect.

  • false (default): Automatically follows redirects and returns the final page content.
  • true: Returns an error on redirect. Useful for detecting URL changes or validating canonical URLs.

Full API Reference

For complete API specification including all endpoints, parameters, and response schemas, see our OpenAPI documentation.

View OpenAPI Reference Download OpenAPI Spec
Icon