Predefined Scrapers API
The Predefined Scrapers API is currently in beta. Parameters and response shapes may change in future releases. 🚧
The Predefined Scrapers API is only available for Cloud plans. Contact us for more information here.
Predefined scrapers return validated JSON from supported sites without browser code, at a fixed price per call. Discover the available scrapers, search Zillow listings, look up an individual property, or fetch the raw HTML of a Google search results page.
When to use: Use this API when a scraper exists for your site. Use Smart Scrape for other single pages and BrowserQL for custom flows.
Endpoint
- List:
GET /scrapers - Run:
POST /scrapers/{scraper}/{api} - Auth:
tokenquery parameter (?token=YOUR_API_TOKEN_HERE) orAuthorization: Bearer YOUR_API_TOKEN_HERE - Content-Type:
application/jsonfor POST requests - Response:
application/json, compressed with Brotli or gzip when your client sendsAccept-Encoding(see Response compression)
- A Browserless API token from your account dashboard
Quickstart
Search for homes for sale in Austin, TX. Run JavaScript server-side with Node.js (not in a browser, where your token would be exposed). The Python examples use requests; install it with python -m pip install requests.
- cURL
- JavaScript
- Python
curl --request POST \
--url 'https://production-sfo.browserless.io/scrapers/zillow/search?token=YOUR_API_TOKEN_HERE' \
--header 'Content-Type: application/json' \
--data '{"params":{"query":"Austin, TX","tenure":"sale"}}'
const TOKEN = "YOUR_API_TOKEN_HERE";
const response = await fetch(
`https://production-sfo.browserless.io/scrapers/zillow/search?token=${TOKEN}`,
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ params: { query: "Austin, TX", tenure: "sale" } }),
},
);
const result = await response.json();
console.log(result);
TOKEN = "YOUR_API_TOKEN_HERE"
import requests
response = requests.post(
f"https://production-sfo.browserless.io/scrapers/zillow/search?token={TOKEN}",
json={"params": {"query": "Austin, TX", "tenure": "sale"}},
)
print(response.json())
Response (abridged example; listings and counts change):
{
"ok": true,
"data": {
"query": { "text": "Austin, TX", "regionId": 10221, "regionType": 6, "subType": "CITY", "label": "Austin, TX", "tenure": "sale", "currency": "USD" },
"page": 1,
"pageCount": 20,
"pageSize": 41,
"totalUnits": 5575,
"exhausted": false,
"via": "api",
"results": [
{
"kind": "home",
"zpid": "29365471",
"url": "https://www.zillow.com/homedetails/15205-Back-Of-The-Moon-St-Austin-TX-78734/29365471_zpid/",
"address": { "line": "15205 Back Of The Moon St, Austin, TX 78734", "street": "15205 Back Of The Moon St", "city": "Austin", "state": "TX", "zip": "78734", "latitude": 30.410772, "longitude": -97.917114 },
"price": { "amount": 475000, "currency": "USD", "period": "total", "text": "$475,000" },
"beds": 3,
"baths": 2,
"livingAreaSqft": 1800,
"lotArea": { "value": 9400.248, "units": "sqft" },
"homeType": "SINGLE_FAMILY",
"status": "FOR_SALE",
"statusText": "Active",
"daysOnZillow": 4,
"imgSrc": "https://photos.zillowstatic.com/fp/f2fb36cf6cea9d2eeac4b4b3f6509f16-p_e.jpg",
"brokerName": "LPT Realty LLC - Ascend Group",
"building": null
}
// …40 more results omitted.
]
},
"error": null
}
totalUnits is Zillow's count of matching listings, not Browserless billing units. This call costs 10 Browserless units, regardless of how many listings it returns.
Check both the HTTP status and ok: a scraper can return HTTP 200 with ok: false. See Error responses.
List the available scrapers
GET /scrapers is free and isn't metered. Use it to discover scraper names, supported hostnames, API names, prices, and output schemas. Examples use San Francisco; see the regional endpoints for other regions.
- cURL
- JavaScript
- Python
curl --request GET \
--url 'https://production-sfo.browserless.io/scrapers?token=YOUR_API_TOKEN_HERE'
const TOKEN = "YOUR_API_TOKEN_HERE";
const response = await fetch(
`https://production-sfo.browserless.io/scrapers?token=${TOKEN}`,
);
console.log(await response.json());
TOKEN = "YOUR_API_TOKEN_HERE"
import requests
response = requests.get(
f"https://production-sfo.browserless.io/scrapers?token={TOKEN}"
)
print(response.json())
Response (catalog v1.4.1 excerpt; schemas and deployment-specific metadata omitted):
{
"version": "1.4.1",
"contractVersion": 2,
// previousVersion and swap metadata omitted.
"scrapers": {
"zillow": {
"hostnames": ["zillow.com", "www.zillow.com"],
"apis": {
"search": { "ttlSeconds": 1800, "units": 10, "outputSchema": { /* … */ } },
"property": { "ttlSeconds": 21600, "units": 10, "outputSchema": { /* … */ } }
}
},
"google": {
"hostnames": ["google.com", "www.google.com"],
"apis": {
"search": { "ttlSeconds": 300, "units": 4, "unitVariants": { "js": 10 }, "outputSchema": { /* … */ } },
"goto": { "ttlSeconds": 60, "units": 1, "outputSchema": { /* … */ } }
}
},
"example": {
"hostnames": ["example.com", "www.example.com"],
"apis": {
"page-info": { "ttlSeconds": 86400, "units": 1, "outputSchema": { /* … */ } }
}
}
}
}
units is the current price per call, and outputSchema is the JSON Schema every successful result is validated against. unitVariants, when present, lists other prices a call of that API can cost by name. For example, a Google search with js_rendering costs the js variant, 10 units. ttlSeconds is how long a result is considered fresh. hostnames is the site's main hostnames; an API can accept more, such as Google's country domains. The catalog also includes previousVersion (a string or null) and swap metadata: inProgress, targetVersion, startedAt, lastOutcome, and lastAt.
Zillow search
Send either params.query or a Zillow place url to POST /scrapers/zillow/search. A listing URL belongs to Zillow property, not search.
Request body
| Parameter | Type | Default | Description |
|---|---|---|---|
url | string | — | Alternative to params.query: a Zillow place URL such as /homes/<slug>_rb/, /<city>-<st>/, a rentals URL, or a Zillow URL containing ?searchQueryState=. Only zillow.com and www.zillow.com are supported. |
params.query | string | — | Place text, for example Austin, TX. Required when you don't supply a place URL. |
params.tenure | string | sale | sale or rent. A value that contradicts the URL, such as sale with a rentals URL, returns invalid-input. |
params.page | integer | 1 | Page from 1 through 24. |
params.sort | string | Site default | Sale: pricea, priced, days, beds, baths, size, lot, priorityscore, zest, zesta. Rent: paymenta, paymentd, days, beds, baths, size, lot, priorityscore. |
params.priceMin, params.priceMax | number | Unset | Minimum and maximum price. For rent, these bound monthly rent. |
params.bedsMin, params.bedsMax | number | Unset | Minimum and maximum bedrooms. |
params.bathsMin, params.bathsMax | number | Unset | Minimum and maximum bathrooms. |
params.sqftMin, params.sqftMax | number | Unset | Minimum and maximum living area in square feet. |
params.yearBuiltMin, params.yearBuiltMax | number | Unset | Earliest and latest construction year. |
params.homeTypes | string | Unset | Comma-separated house, condo, townhouse, apartment, multifamily, manufactured, land. Listing one switches the others off. |
params.daysOnZillow | string | Unset | One of 1, 7, 14, 30, 90, 6m, 12m, 24m, 36m. |
params.keywords | string | Unset | 1–200 printable characters. |
For all scraper requests, url is limited to 8,192 characters. params accepts at most 64 keys, with keys up to 128 characters and values up to 4,096 characters. Values must be strings, numbers, or booleans, not nested objects or arrays.
Response fields
Successful responses have ok: true, the following fields under data, and error: null.
| Field | Description |
|---|---|
query | Resolved place: text, regionId, regionType, subType, label, tenure, and currency (USD or CAD). |
page, pageCount, pageSize | Current page, Zillow's displayed page count (capped at 20), and page size (41). Pages 21–24 can still return results. |
totalUnits | Number of matching listings, not a charge. |
exhausted | true when the requested page is past the real end and has no results. |
via | api or browser, indicating which extraction path succeeded. |
results[] | Matching homes or buildings. |
results[].kind, zpid, url | kind is home or building; zpid is a string identifier; url links to Zillow. |
results[].address | line, street, city, state, zip, latitude, and longitude. |
results[].price | amount, currency, period, and display text. |
results[].beds, baths, livingAreaSqft, lotArea | Property dimensions. lotArea contains value and units. |
results[].homeType, status, statusText, daysOnZillow | Property type, listing status, and listing age. |
results[].imgSrc, brokerName, building | Photo URL, brokerage, and building information. building is null for a home result. |
Filter rentals
Find rentals with at least two bedrooms and monthly rent no higher than $2,500, sorted by ascending payment:
curl --request POST \
--url 'https://production-sfo.browserless.io/scrapers/zillow/search?token=YOUR_API_TOKEN_HERE' \
--header 'Content-Type: application/json' \
--data '{"params":{"query":"Austin, TX","tenure":"rent","bedsMin":2,"priceMax":2500,"sort":"paymenta"}}'
Response uses the search envelope above, with data.query.tenure set to rent. Prices describe rent rather than a sale price; counts and listings depend on current availability.
Zillow property
Call POST /scrapers/zillow/property with a property ID or a Zillow listing URL. Building URLs aren't accepted.
| Parameter | Type | Default | Description |
|---|---|---|---|
params.zpid | string or integer | — | Positive property ID as a digit-only string or integer, at most 2,147,483,647. Use a zpid from a search result. |
url | string | — | Alternative to params.zpid: https://www.zillow.com/homedetails/…/<zpid>_zpid/. |
curl --request POST \
--url 'https://production-sfo.browserless.io/scrapers/zillow/property?token=YOUR_API_TOKEN_HERE' \
--header 'Content-Type: application/json' \
--data '{"params":{"zpid":29365471}}'
Response (excerpt; values change as the listing changes):
{
"ok": true,
"data": {
"identity": { "zpid": "29365471", "url": "https://www.zillow.com/homedetails/15205-Back-Of-The-Moon-St-Austin-TX-78734/29365471_zpid/", "homeStatus": "FOR_SALE", "homeType": "SINGLE_FAMILY", "tenure": "sale", "country": "USA", "currency": "USD", "buildingId": null, "providerListingId": null },
"address": { "street": "15205 Back Of The Moon St", "city": "Austin", "state": "TX", "zip": "78734", "neighborhood": null, "subdivision": "Travis Landing", "county": "Travis County", "latitude": 30.410772, "longitude": -97.917114, "parcelId": "156788" },
"price": { "list": 475000, "zestimate": null, "rentZestimate": null, "lastSold": null, "listLow": null, "baseRent": null, "pricePerSqft": 264, "hoaFeeText": "$166 annually", "taxAssessedValue": 362528 },
// facts, listing, history, schools, photos, media, and rental omitted.
"via": "api"
},
"error": null
}
| Group | Description |
|---|---|
identity | Property and provider identifiers, URL, status, home type, country, currency, and tenure (sale, rent, or other). The returned zpid is a string. |
address | Street, city, state, ZIP, neighborhood, subdivision, county, coordinates, and parcel ID. Unlike search results, it has no line field. |
price | Listing price, estimates, last sale, rent, price per square foot, HOA text, and assessed value. Unavailable values can be null. |
facts, listing, history | Property characteristics, listing information, and historical records. |
schools[], photos[] | School information and property photos. |
media, rental | Additional media and rental details. |
via | api or browser. |
Use the catalog's outputSchema for the full field definitions.
Google search
POST /scrapers/google/search returns the HTML of a Google search results page for a search URL you build. Unlike the Zillow scrapers, it doesn't parse the page: you get Google's own HTML, so you parse the results, ads, and other features yourself. Use it when you need the page exactly as Google served it.
- cURL
- JavaScript
- Python
curl --request POST \
--url 'https://production-sfo.browserless.io/scrapers/google/search?token=YOUR_API_TOKEN_HERE' \
--header 'Content-Type: application/json' \
--compressed \
--data '{"url":"https://www.google.com/search?q=best+running+shoes&hl=en&gl=us"}'
const TOKEN = "YOUR_API_TOKEN_HERE";
const response = await fetch(
`https://production-sfo.browserless.io/scrapers/google/search?token=${TOKEN}`,
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
url: "https://www.google.com/search?q=best+running+shoes&hl=en&gl=us",
}),
},
);
// fetch sends Accept-Encoding and decompresses the response for you.
const result = await response.json();
if (result.ok) {
console.log(result.data.url, result.data.html.length);
} else {
console.log(result.error);
}
TOKEN = "YOUR_API_TOKEN_HERE"
import requests
response = requests.post(
f"https://production-sfo.browserless.io/scrapers/google/search?token={TOKEN}",
json={"url": "https://www.google.com/search?q=best+running+shoes&hl=en&gl=us"},
)
# requests decompresses gzip for you, and Brotli too if the brotli package is installed.
result = response.json()
if result["ok"]:
print(result["data"]["url"], len(result["data"]["html"]))
else:
print(result["error"])
Response (html abridged; a full results page is about 1 MB before compression):
{
"ok": true,
"data": {
"html": "<!doctype html><html itemscope=\"\" itemtype=\"http://schema.org/SearchResultsPage\" lang=\"en\">…</html>",
"url": "https://www.google.com/search?q=best+running+shoes&hl=en&gl=us"
},
"error": null
}
Request body
| Parameter | Type | Default | Description |
|---|---|---|---|
url | string | — | A Google search URL: path /search with a non-empty q parameter, on any of Google's search domains such as www.google.com or www.google.co.uk. The scheme is optional, and http:// is upgraded to https://. The URL must be percent-encoded: no spaces, quotes, <, >, {, }, |, \, ^, or backticks. For example, write %22 for a quote in an exact-phrase search. It must also be at most 4,096 characters and have no port or credentials. |
params.js_rendering | boolean | false | false returns the page as Google sent it, without running JavaScript. true renders the page in a browser, expands the AI Overview when the page has one, and returns the rendered HTML. A JavaScript search costs more and takes longer; see Render JavaScript and AI Overviews. |
params.device | string | desktop | Only desktop is available. mobile and tablet return invalid-input for now. |
No other params keys are accepted. The scraper fetches your URL as you send it, so its query parameters control the results. Requests leave from US IP addresses, so use hl for the interface language, gl for the results country, and uule for a precise location when you need results for another market. Pagination works the same way: send Google's start parameter, for example &start=10 for the second page. Each page is a separate call.
Response fields
| Field | Description |
|---|---|
html | Without js_rendering, the HTML document as Google returned it (in rare cases, the page as loaded in the browser instead). With js_rendering, the rendered DOM (document.documentElement.outerHTML) after the page loaded and any AI Overview was expanded. Always plain text, never base64. |
url | Final URL of the search results page. |
html is large, so let your client compress the response (see Response compression).
Render JavaScript and AI Overviews
Some results only appear after Google's JavaScript runs, most visibly the AI Overview. Set params.js_rendering to true to get the page after it renders:
curl --request POST \
--url 'https://production-sfo.browserless.io/scrapers/google/search?token=YOUR_API_TOKEN_HERE' \
--header 'Content-Type: application/json' \
--compressed \
--data '{"url":"https://www.google.com/search?q=how+do+solar+panels+work&hl=en&gl=us","params":{"js_rendering":true}}'
Response uses the same envelope, with data.html holding the rendered page. A JavaScript search costs 10 units instead of 4 and usually takes about 12 seconds instead of about 2, so only enable it when you need content that JavaScript adds.
Google goto
POST /scrapers/google/goto resolves a Google redirect link, such as an ad link or a /url?q= result link from a results page, without following it. Use it to find where a link leads without visiting the destination.
| Parameter | Type | Default | Description |
|---|---|---|---|
url | string | — | A URL on one of Google's search domains, with the same format rules as Google search, but any path. Links on other hosts, such as ad links on googleadservices.com, return invalid-input. goto takes no params; sending any returns invalid-input. |
curl --request POST \
--url 'https://production-sfo.browserless.io/scrapers/google/goto?token=YOUR_API_TOKEN_HERE' \
--header 'Content-Type: application/json' \
--data '{"url":"https://www.google.com/url?q=https://www.example.com/&sa=U"}'
Response (Google answers this unsigned /url?q= link with its redirect-notice page rather than a redirect):
{
"ok": true,
"data": { "status": 200, "location": null },
"error": null
}
For a link that Google does redirect, status is the redirect status, such as 302, and location holds the destination URL.
| Field | Description |
|---|---|
status | The HTTP status Google answered with. |
location | The redirect target from Google's Location header when status is a redirect (3xx); null otherwise. |
A status of 200 with location: null means Google answered with a page instead of a redirect, for example its redirect-notice page for a link it won't forward automatically. A call that returns ok: true costs 1 unit, whatever status Google answered with. If Google answers with 429 or its CAPTCHA page on every attempt, the call returns blocked and is free.
Pricing
A call is charged the API's fixed units only when it returns HTTP 200 with ok: true or error.code: "not-found"; every other outcome is free, including timeouts and 429s. No browser-time, proxy, or CAPTCHA units are added, and the charge appears under Time units on your account dashboard.
| API | Units per charged call |
|---|---|
zillow.search | 10 |
zillow.property | 10 |
google.search | 4 (10 with params.js_rendering: true) |
google.goto | 1 |
example.page-info | 1 |
A Google search with JavaScript rendering costs more because it runs in a browser; the catalog lists that price under unitVariants.js. A blocked Google search is free, like every other error outcome.
GET /scrapers always returns the current price for every API. See Unit consumption for your allowance and usage tracking.
Response compression
Scraper results from POST /scrapers/{scraper}/{api} (HTTP 200, including ok: false) are compressed when your client accepts it. Send Accept-Encoding: br or Accept-Encoding: gzip, and the response comes back with a matching Content-Encoding header. This matters most for Google search, where a results page of about 970 KB of JSON arrives as about 300 KB with Brotli.
- Brotli or gzip: your client's
qweights decide. Brotli wins a tie because it's smaller at the same cost. - No
Accept-Encoding: the JSON comes back uncompressed. Results under 1 KB, such as mostok: falseenvelopes, are also sent uncompressed. - Host errors: 4xx and 5xx responses, such as
job-timeoutoroverloaded, are always plain JSON. - Caching: scraper results include
Vary: Accept-Encoding.
Most clients handle this for you:
| Client | What to do |
|---|---|
| cURL | Add --compressed. Without it, cURL doesn't send Accept-Encoding and gets uncompressed JSON. |
JavaScript fetch (Node.js 18+) | Nothing. It sends Accept-Encoding and decompresses automatically. |
Python requests | Nothing for gzip. Install brotli (python -m pip install brotli) to receive Brotli instead. |
The compression is transport-level only. After your client decodes it, the body is the same JSON envelope, and data.html is plain text.
Testing cheaply
Use example.page-info to check authentication and response handling for 1 unit. It accepts only example.com or www.example.com URLs and returns title and heading; heading uses the first paragraph if the page has no heading.
curl --request POST --url 'https://production-sfo.browserless.io/scrapers/example/page-info?token=YOUR_API_TOKEN_HERE' --header 'Content-Type: application/json' --data '{"url":"https://example.com/"}'
Response contains ok: true, data.title: "Example Domain", data.heading with the page's heading or first paragraph, and error: null.
Timeouts and concurrency
Set the timeout query parameter in milliseconds, for example &timeout=90000. Without it, your plan's maximum session time applies, capped at the server ceiling of 30 minutes. Values above the server ceiling are clamped, but a value above your plan's maximum session time returns HTTP 400 rather than extending the plan limit. Zero, negative, and non-numeric values also return 400.
Allow at least 90,000 ms for Zillow, and keep your HTTP client's timeout longer than the API timeout. The API path usually finishes in a few seconds, but a blocked request can fall back to a stealth browser and take about 90 seconds.
Allow at least 120,000 ms for Google search. Most searches finish in about 2 seconds, or about 12 seconds with js_rendering, but a search occasionally takes several minutes when the scraper has to prepare a fresh browser session first. If you'd rather wait than retry, use timeout=420000 (within your plan's maximum session time) and raise your HTTP client's timeout to match. Node's built-in fetch stops waiting for response headers after 300 seconds by default. A timed-out call returns job-timeout and costs nothing. google.goto usually answers within seconds; 60,000 ms is enough.
Scraper calls count toward your plan's concurrency limit like any other request, for as long as the call is in flight. Above the limit you get 429 Too Many Requests; it costs nothing, so retry with backoff.
Error responses
Scraper errors return HTTP 200 with ok: false; host and platform failures use HTTP error statuses. Check the HTTP status first, then inspect error.retryable only if the body contains a scraper error envelope. Use backoff for transient failures.
| Status | Code | Charged | What it means / what to do |
|---|---|---|---|
| 200 | not-found | Yes | The lookup ran but no property or region matched. Check the query or property ID; retryable: false. |
| 200 | invalid-input | No | The scraper rejected an input. Correct the field named in message; values aren't echoed. Retryable: false. |
| 200 | blocked | No | For Zillow, bot protection defeated the API path and browser fallback. For Google, it covers any refusal or failure to get an answer from Google. details.stage is api, rotated, or browser for Zillow, and search or goto for Google. A Google search can also return details.reason: "poisoned-results", meaning Google answered with results for a different query; don't treat that page as an answer. Retryable: true. |
| 200 | upstream-changed | No | The site's page or API changed. A scraper update is needed; retryable: false. |
| 200 | upstream-error | No | The site or network failed. Retryable: true. |
| 400 | unknown-scraper / unknown-api | No | Check the path against GET /scrapers. Retryable: false. |
| 400 | input-not-cloneable | No | The body couldn't be handed to the scraper. Correct its structure; retryable: false. |
| 408 | job-timeout | No | The job exceeded timeout. Increase it within your plan limit; retryable: true. |
| 429 | Too Many Requests (platform response) | No | Your plan's concurrency limit is reached, as for every endpoint. Wait for an in-flight request to finish, then retry. This response doesn't use the scraper envelope. |
| 429 | overloaded | No | Rare: the region is at scraper capacity. Retry with backoff; retryable: true. |
| 503 | bundle-unavailable / worker-crashed / job-drained | No | Rare: the scraper runtime is restarting or being updated. Retry with backoff; retryable: true. |
| 500 | invalid-result | No | Output failed schema validation. Report the error; retryable: false. |
| 401 | Unauthorized (platform response) | No | Supply a valid API token. This response doesn't use the scraper envelope. |
For example, a missing property returns HTTP 200 with this envelope (message is abbreviated):
{
"ok": false,
"data": null,
"error": {
"code": "not-found",
"message": "…",
"retryable": false,
"status": null,
"details": null
}
}
error.status and error.details carry additional context when available; they aren't the HTTP response status. Invalid timeout parameters can also produce a plain HTTP 400 platform response, so don't assume every error body is JSON.
FAQ & Troubleshooting
Why am I getting 401 Unauthorized?
Pass a valid API token in ?token= or Authorization: Bearer. Check your token in the account dashboard; don't put it in the JSON body.
I got not-found and was still charged. Why?
The scraper completed the lookup and found no match. That definitive answer costs the same fixed units as a successful lookup. Other error outcomes are free.
I sent a Zillow listing URL to search and got invalid-input
Send /homedetails/…_zpid/ URLs to zillow/property. zillow/search takes a place query or place URL, not an individual listing.
Why did a request take 40+ seconds?
Allow at least 90 seconds for Zillow. When the site's API path is blocked, the scraper can fall back to a stealth browser. A successful result's via field tells you which path returned it; the price doesn't increase for the browser fallback.
My Google search response looks like binary data or won't parse as JSON
Your client asked for a compressed response but didn't decode it. Use cURL's --compressed flag, or a client that decodes Content-Encoding for you, such as fetch or requests. If you set Accept-Encoding by hand, decode the body yourself or remove the header to get plain JSON. See Response compression.
My Google search returned blocked. Should I retry?
Yes. Google refuses a small share of automated searches, and the scraper already retries before it gives up. A blocked result is free, so retry the same URL after a short backoff. If details.reason is poisoned-results, Google answered with results for a different query; wait a little longer before you retry.
Can I get mobile results from Google search?
Not yet. params.device only accepts desktop, and mobile or tablet return invalid-input. The scraper sends a desktop browser profile, so Google serves its desktop results page.
What should I do about 429 Too Many Requests?
Your account is at its plan concurrency limit; scraper calls count toward it while they run. The response costs nothing; retry with backoff.
Next steps
See the OpenAPI reference for complete parameter details.