Browserless

Scrape, search, map and crawl the web; capture pages as screenshots or PDFs and turn your own HTML into PDFs; get past bot detection; run Lighthouse audits, Puppeteer code or BrowserQL; and hand tasks to a managed browser agent, all on Browserless's hosted browsers.

Actions

Action	What it does
Cancel crawl	Stop a running crawl.
Cancel or delete agent run	Stop an agent run that is still going (status becomes stopped), or delete a finished run and its result (status deleted).
Convert HTML to PDF	Turn HTML of your own (an invoice, a report, a certificate) or a web page into a PDF, with the paper size, orientation, margins, and a header and footer with page numbers.
Crawl a site	Start crawling a site: Browserless follows its links (and sitemap) and scrapes every page as markdown, HTML or text.
Download a file with browser code	Run Puppeteer code that makes the browser download a file (click an Export button, say) and save that file to your workspace's file storage.
Export a URL as a file	Open a URL in a real browser and save what it serves as a file in your workspace's file storage: a PDF, an image or other download as is, or a page's HTML.
Extract links from a page	Collect every link on a web page as an absolute http(s) URL.
Get a page's rendered HTML	Load a page in a real browser, let its JavaScript run, and return the HTML it ends up with.
Get agent run	Check an agent run: its status, its answer once it finishes, the steps it has taken, and any page captures.
Get crawl	Check a crawl's progress and get its pages, ten at a time, with each page's markdown, HTML or text.
Get profile	Look up one saved sign-in profile by name, and whether each of its logins is still valid, about to expire or expired.
List agent runs	List your account's agent runs, newest first.
List crawls	List your account's crawls, newest first, with their progress.
List predefined scrapers	List Browserless's ready-made scrapers (Zillow listings and property details today) and what each call costs.
List profiles	List the sign-in profiles saved in Browserless (uploaded with its CLI or API), with how many cookies each holds and whether its logins are still valid.
Map a site	List the pages of a site from its sitemap and its links, with titles and descriptions where known.
Run a BrowserQL query	Run a BrowserQL query: a whole browser session written as GraphQL mutations (go to a page, click, type, solve a captcha, read text) and run in one request.
Run a Lighthouse audit	Run Google Lighthouse on a page and get its performance, accessibility, best-practices and SEO scores out of 100, its speed metrics (Largest Contentful Paint and others), and the audits it failed with Lighthouse's advice.
Run a predefined scraper	Get structured data from a supported site with one of Browserless's ready-made scrapers, at a fixed price per call: search Zillow for homes for sale or rent, or look up a Zillow property.
Run browser code	Run your own Puppeteer code in a Browserless browser, for steps the other actions don't cover: sign in, click through a flow, then return what you found.
Save a page as PDF	Render a web page in a real browser and print it to PDF, getting past bot protection and captchas when needed.
Scrape a page	Fetch a web page and return its HTML, a clean markdown version, its text and its title.
Scrape elements by CSS selector	Load a page in a real browser and pull out the elements matching each CSS selector you give: their text, HTML, attributes and position.
Screenshot a page	Render a web page in a real browser and capture the full page as a PNG, getting past bot protection and captchas when needed.
Search the web	Search the web, news or images, filtered by language, country, date or kind of site, and optionally read each result page as markdown or HTML in the same step.
Start an agent task	Describe a task in plain English and Browserless's managed AI agent does it in a real browser: navigating, clicking, typing and reading.
Take a custom screenshot	Screenshot a page, or HTML of your own, with the details chosen: PNG, JPEG or WebP, the window size, the whole page or just what fits, or one element on it.
Unblock a page	Get past a site's bot detection (Cloudflare, DataDome and passive captchas) and return the page's HTML, the cookies it set, a screenshot, or all three.

Cancel crawl

Stop a running crawl. Pages already scraped stay available to 'Get crawl'. Fails if the crawl has already finished.

Inputs

Crawl IDcrawl_idtextRequired: The crawl's ID, from 'Crawl a site' or 'List crawls'.

Outputs

crawl_idtext: The crawl's ID
statustext: cancelled

Example output

{
  "crawl_id": "crawl_abc123def456",
  "status": "cancelled"
}

Cancel or delete agent run

Stop an agent run that is still going (status becomes stopped), or delete a finished run and its result (status deleted).

Inputs

Run IDrun_idtextRequired: The agent run's ID, from 'Start an agent task' or 'List agent runs'.

Outputs

run_idtext: The run's ID
statustext: stopped or deleted

Example output

{
  "run_id": "run_abc123def456",
  "status": "stopped"
}

Convert HTML to PDF

Turn HTML of your own (an invoice, a report, a certificate) or a web page into a PDF, with the paper size, orientation, margins, and a header and footer with page numbers. Text stays real, selectable text. The file is saved to your workspace's file storage.

Inputs

HTMLhtmltext: The HTML to print, with any CSS in <style> tags. Fill in either this or the page URL.
Page URLurltext: A page to print instead, starting with http:// or https://. Leave empty when printing HTML.
Paper sizepaper_formattext: Optional. Letter unless chosen otherwise.One of: letter (Letter (8.5 x 11 in)), legal (Legal (8.5 x 14 in)), tabloid (Tabloid (11 x 17 in)), ledger (Ledger (17 x 11 in)), a0, a1, a2, a3, a4 (A4 (210 x 297 mm)), a5, a6.
Landscapelandscapetrue/false: Print sideways.Default: false.
Print backgroundsprint_backgroundtrue/false: Print background colours and images, as the page shows them on screen.Default: true.
Marginsmargintext: Optional. One margin for all four sides, such as 1cm, 0.5in or 20px.
Scalescalenumber: Optional. Zoom from 0.1 to 2; 1 is actual size.From 0.1 to 2.
Pagespage_rangestext: Optional. Which pages to keep, such as 1-5, 8, 11-13.
Headerheader_templatetext: Optional. HTML for the top of every page. Elements with the class pageNumber, totalPages, date, title or url are filled in. Set a font-size, as it starts tiny, and leave room for it with a margin.
Footerfooter_templatetext: Optional. HTML for the bottom of every page, filled in the same way as the header.
Use the page size in the CSSprefer_css_page_sizetrue/false: Use a size set by an @page rule in the HTML over the paper size.Default: false.
Accessible PDFtaggedtrue/false: Tag the PDF with the HTML's structure (headings, reading order) for screen readers and parsers.Default: false.
Bookmarksoutlinetrue/false: Add bookmarks built from the HTML's headings.Default: false.
Styles to usemedia_typetext: Optional. Whether the page's print styles apply (the default) or its on-screen ones.One of: print (Print styles), screen (Screen styles: as it looks in a browser).
Hide cookie bannersblock_consent_modalstrue/false: Close cookie-consent banners and pop-ups before the capture.Default: false.
Wait for elementwait_for_selectortext: Optional. CSS selector of an element to wait for before reading the page, such as #results or .price. The step fails if it never appears, unless 'Carry on if waiting times out' is on.
Wait after loading (seconds)wait_secondsnumber: Optional. Seconds to let the page fill itself in after it loads, up to 30.From 0 to 30.
Page counts as loaded whenwait_untiltext: Optional. When navigation is done. Browserless's default is Load.One of: load (Load: everything, images included, has loaded), domcontentloaded (The HTML is parsed (fastest)), networkidle0 (No network requests for half a second), networkidle2 (At most two network requests for half a second).
Carry on if waiting times outbest_attempttrue/false: Use the page as it is when a wait or the navigation times out, instead of failing the step.Default: false.
Stealth modestealthtrue/false: Hide the signs of an automated browser from bot detection. Turn on for sites that block or challenge headless browsers.Default: false.
Proxy networkproxytext: Optional. Route the browser through Browserless's proxies, for sites that block cloud servers. Proxies spend extra units per MB. Leave empty to connect directly.One of: residential (Residential: harder to block), datacenter (Datacenter: cheaper, blocked more often).
Proxy countryproxy_countrytext: Optional. Two-letter code of the country to browse from, such as US, GB or DE, for sites that change by location. Uses the residential proxy unless another network is chosen.
Block adsblock_adstrue/false: Load the page with an ad blocker, so ads and trackers don't load.Default: false.
Sign-in profileprofiletext: Optional. Name of a profile saved in Browserless, so the browser starts signed in with its cookies and storage. 'List profiles' shows the names.
Give up after (seconds)timeout_secondsnumber: Optional. Seconds Browserless may spend on the request before it stops. Your plan sets the default and the most allowed.From 1 to 900.
File namefilenametext: Optional. Name to store the PDF under, such as invoice-1042.pdf. Leave empty to name it after the page.

Outputs

byte_sizenumber: Size of the PDF in bytes
content_typetext: MIME type of the PDF
document_reftext: ID of the stored PDF, for a later step that takes a file
documentslist: The PDF, saved to your workspace's file storage
filenametext: Name the PDF was stored under
final_urltext: Where the page ended up after any redirects
page_urltext: The page that was loaded, or empty for rendered HTML
status_codenumber: HTTP status the site answered with, or 0 for rendered HTML
urltext: Link that serves the PDF

Example output

{
  "byte_size": 31744,
  "content_type": "application/pdf",
  "document_ref": "doc_9f8e7d6c5b4a3210",
  "documents": [
    {
      "content_type": "application/pdf",
      "document_ref": "doc_9f8e7d6c5b4a3210",
      "filename": "invoice-1042.pdf",
      "size_bytes": 31744,
      "url": "/actions/core/serve-document/doc_9f8e7d6c5b4a3210?teamId=6512a1b2c3d4e5f600000001"
    }
  ],
  "filename": "invoice-1042.pdf",
  "final_url": "",
  "page_url": "",
  "status_code": 0,
  "url": "/actions/core/serve-document/doc_9f8e7d6c5b4a3210?teamId=6512a1b2c3d4e5f600000001"
}

Crawl a site

Start crawling a site: Browserless follows its links (and sitemap) and scrapes every page as markdown, HTML or text. The crawl runs in the background; follow it with 'Get crawl', which returns the pages. Cloud plans only; in beta at Browserless.

Inputs

Site URLurltextRequired: The site to start from, starting with http:// or https://.
At mostlimitnumber: Optional. The most pages to crawl. Browserless crawls 100, and your plan sets the most.From 1 to 10000.
Links deepmax_depthnumber: Optional. How many links away from the start page to go, 0 to 20. Browserless goes 5.From 0 to 20.
Follow links to subdomainsallow_subdomainstrue/false: Also crawl subdomains, such as blog.example.com.Default: false.
Follow links to other sitesallow_external_linkstrue/false: Also crawl pages on other domains the site links to.Default: false.
Sitemapsitemaptext: Optional. How to use the site's sitemap.One of: auto (Use it if there is one (default)), force (Only pages in the sitemap), skip (Ignore it and follow links).
Only paths matchinginclude_pathslist: Optional. Regular expressions a page's path must match, such as ^/blog.
Skip paths matchingexclude_pathslist: Optional. Regular expressions of paths to skip, such as ^/blog/tag.
Bring backformatslist: Optional. What each page comes back as; markdown if none.One or more of: markdown, html, rawText (Text).
Skip navigation and footersonly_main_contenttrue/false: Keep only each page's main content. On unless turned off.Default: true.
Wait after loading (seconds)wait_secondsnumber: Optional. Seconds to let the page fill itself in after it loads, up to 30.From 0 to 30.
Proxy networkproxytext: Optional. Route the browser through Browserless's proxies, for sites that block cloud servers. Proxies spend extra units per MB. Leave empty to connect directly.One of: residential (Residential: harder to block), datacenter (Datacenter: cheaper, blocked more often).
Webhook URLwebhook_urltext: Optional. An https:// address Browserless calls when the job finishes, such as a Lodol webhook trigger.
Call the webhook whenwebhook_eventslist: Optional. Which events to send. Completion only if none.One or more of: page (Each page is scraped), completed (The crawl completes), failed (The crawl fails).
Sign-in profileprofiletext: Optional. Name of a profile saved in Browserless, so the browser starts signed in with its cookies and storage. 'List profiles' shows the names.

Outputs

crawl_idtext: The crawl's ID, for 'Get crawl'
urltext: Where the crawl starts

Example output

{
  "crawl_id": "crawl_abc123def456",
  "url": "https://docs.browserless.io"
}

Download a file with browser code

Run Puppeteer code that makes the browser download a file (click an Export button, say) and save that file to your workspace's file storage. For a file you have a direct link to, 'Export a URL as a file' is simpler.

Inputs

CodecodetextRequired: A JavaScript module whose default export is an async function. It gets { page, context }, where page is a Puppeteer page, and must wait for the download to finish.
Contextcontextobject: Optional. Values to hand the code as context, such as a URL or a search term from an earlier step.
Stealth modestealthtrue/false: Hide the signs of an automated browser from bot detection. Turn on for sites that block or challenge headless browsers.Default: false.
Proxy networkproxytext: Optional. Route the browser through Browserless's proxies, for sites that block cloud servers. Proxies spend extra units per MB. Leave empty to connect directly.One of: residential (Residential: harder to block), datacenter (Datacenter: cheaper, blocked more often).
Proxy countryproxy_countrytext: Optional. Two-letter code of the country to browse from, such as US, GB or DE, for sites that change by location. Uses the residential proxy unless another network is chosen.
Block adsblock_adstrue/false: Load the page with an ad blocker, so ads and trackers don't load.Default: false.
Sign-in profileprofiletext: Optional. Name of a profile saved in Browserless, so the browser starts signed in with its cookies and storage. 'List profiles' shows the names.
Give up after (seconds)timeout_secondsnumber: Optional. Seconds Browserless may spend on the request before it stops. Your plan sets the default and the most allowed.From 1 to 900.
File namefilenametext: Optional. Name to store the file under. Browserless often doesn't pass on the name the site gave the file, and then it is stored as download plus its extension.

Outputs

byte_sizenumber: Size of the downloaded file in bytes
content_typetext: MIME type of the downloaded file
document_reftext: ID of the stored downloaded file, for a later step that takes a file
documentslist: The downloaded file, saved to your workspace's file storage
filenametext: Name the downloaded file was stored under
urltext: Link that serves the downloaded file

Example output

{
  "byte_size": 8412,
  "content_type": "text/csv",
  "document_ref": "doc_9f8e7d6c5b4a3210",
  "documents": [
    {
      "content_type": "text/csv",
      "document_ref": "doc_9f8e7d6c5b4a3210",
      "filename": "report.csv",
      "size_bytes": 8412,
      "url": "/actions/core/serve-document/doc_9f8e7d6c5b4a3210?teamId=6512a1b2c3d4e5f600000001"
    }
  ],
  "filename": "report.csv",
  "url": "/actions/core/serve-document/doc_9f8e7d6c5b4a3210?teamId=6512a1b2c3d4e5f600000001"
}

Export a URL as a file

Open a URL in a real browser and save what it serves as a file in your workspace's file storage: a PDF, an image or other download as is, or a page's HTML. Can also zip a page with all its images, styles and scripts for an offline copy.

Inputs

Page URLurltextRequired: The page to load, starting with http:// or https://.
Zip with images and stylesinclude_resourcestrue/false: Save a zip of the page's HTML with every image, stylesheet and script it uses.Default: false.
Wait for elementwait_for_selectortext: Optional. CSS selector of an element to wait for before reading the page, such as #results or .price. The step fails if it never appears, unless 'Carry on if waiting times out' is on.
Wait after loading (seconds)wait_secondsnumber: Optional. Seconds to let the page fill itself in after it loads, up to 30.From 0 to 30.
Page counts as loaded whenwait_untiltext: Optional. When navigation is done. Browserless's default is Load.One of: load (Load: everything, images included, has loaded), domcontentloaded (The HTML is parsed (fastest)), networkidle0 (No network requests for half a second), networkidle2 (At most two network requests for half a second).
Carry on if waiting times outbest_attempttrue/false: Use the page as it is when a wait or the navigation times out, instead of failing the step.Default: false.
Request headersheadersobject: Optional. Extra HTTP headers to send with every request the page makes, such as Accept-Language.
Stealth modestealthtrue/false: Hide the signs of an automated browser from bot detection. Turn on for sites that block or challenge headless browsers.Default: false.
Proxy networkproxytext: Optional. Route the browser through Browserless's proxies, for sites that block cloud servers. Proxies spend extra units per MB. Leave empty to connect directly.One of: residential (Residential: harder to block), datacenter (Datacenter: cheaper, blocked more often).
Proxy countryproxy_countrytext: Optional. Two-letter code of the country to browse from, such as US, GB or DE, for sites that change by location. Uses the residential proxy unless another network is chosen.
Block adsblock_adstrue/false: Load the page with an ad blocker, so ads and trackers don't load.Default: false.
Sign-in profileprofiletext: Optional. Name of a profile saved in Browserless, so the browser starts signed in with its cookies and storage. 'List profiles' shows the names.
Give up after (seconds)timeout_secondsnumber: Optional. Seconds Browserless may spend on the request before it stops. Your plan sets the default and the most allowed.From 1 to 900.
File namefilenametext: Optional. Name to store the file under. Leave empty to name it after the page.

Outputs

byte_sizenumber: Size of the file in bytes
content_typetext: MIME type of the file
document_reftext: ID of the stored file, for a later step that takes a file
documentslist: The file, saved to your workspace's file storage
filenametext: Name the file was stored under
final_urltext: Where the URL ended up after any redirects
page_urltext: The URL exported
status_codenumber: HTTP status the site answered with, or 0
urltext: Link that serves the file

Example output

{
  "byte_size": 13264,
  "content_type": "application/pdf",
  "document_ref": "doc_9f8e7d6c5b4a3210",
  "documents": [
    {
      "content_type": "application/pdf",
      "document_ref": "doc_9f8e7d6c5b4a3210",
      "filename": "dummy.pdf",
      "size_bytes": 13264,
      "url": "/actions/core/serve-document/doc_9f8e7d6c5b4a3210?teamId=6512a1b2c3d4e5f600000001"
    }
  ],
  "filename": "dummy.pdf",
  "final_url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
  "page_url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
  "status_code": 200,
  "url": "/actions/core/serve-document/doc_9f8e7d6c5b4a3210?teamId=6512a1b2c3d4e5f600000001"
}

Extract links from a page

Collect every link on a web page as an absolute http(s) URL. Useful for walking a site: feed the list into a loop and scrape each page in turn. Keep only some parts of the page to collect just their links.

Inputs

Page URLurltextRequired: The page to load, starting with http:// or https://.
Proxy networkproxytext: Optional. Which proxy network to route through if the site blocks the first, direct attempt. Leave empty to use Browserless's default (residential).One of: residential (Residential: harder to block), datacenter (Datacenter: cheaper, blocked more often).
Proxy countryproxy_countrytext: Optional. Two-letter code of the country the proxy should exit from, such as US, GB or DE, if the site needs a proxy.
Skip navigation and footersonly_main_contenttrue/false: Leave out navigation, footers, sidebars, scripts and styles. Can't be combined with 'Only these parts'.Default: false.
Only these partsinclude_tagslist: Optional. CSS selectors of the parts to keep, such as article or .price, up to 100. The whole page comes back if none match.
Leave out these partsexclude_tagslist: Optional. CSS selectors of the parts to drop, such as nav or #cookie-banner, up to 100. Can't be combined with 'Only these parts'.
Wait after loading (seconds)wait_secondsnumber: Optional. Seconds to let the page fill itself in after it loads, up to 30. Any wait makes Browserless use a real browser.From 0 to 30.
Do firstbrowser_actionslist: Optional. Up to 20 steps to run in the page before it is read, such as closing a cookie banner or typing a search. Each has a type (wait, click, write, scroll, scrape or executeJavascript) and the fields it needs. Any step makes Browserless use a real browser.
Sign-in profileprofiletext: Optional. Name of a profile saved in Browserless, so the browser starts signed in with its cookies and storage. 'List profiles' shows the names.

Outputs

linkslist: Every http(s) link on the page, as absolute URLs
status_codenumber: HTTP status the page responded with
strategytext: How Browserless fetched the page: http-fetch, http-proxy, browser or browser-captcha
titletext: The page's title
urltext: The page that was read

Example output

{
  "links": [
    "https://news.ycombinator.com/newest",
    "https://news.ycombinator.com/front"
  ],
  "status_code": 200,
  "strategy": "http-fetch",
  "title": "Hacker News",
  "url": "https://news.ycombinator.com/"
}

Get a page's rendered HTML

Load a page in a real browser, let its JavaScript run, and return the HTML it ends up with. Wait for an element to appear, skip images and fonts to save time, or render HTML of your own instead of a URL.

Inputs

Page URLurltext: The page to load, starting with http:// or https://. Leave empty to render the HTML instead.
HTMLhtmltext: HTML to render instead of loading a page, with any CSS in <style> tags. Fill in either this or the page URL.
Wait for elementwait_for_selectortext: Optional. CSS selector of an element to wait for before reading the page, such as #results or .price. The step fails if it never appears, unless 'Carry on if waiting times out' is on.
Wait after loading (seconds)wait_secondsnumber: Optional. Seconds to let the page fill itself in after it loads, up to 30.From 0 to 30.
Page counts as loaded whenwait_untiltext: Optional. When navigation is done. Browserless's default is Load.One of: load (Load: everything, images included, has loaded), domcontentloaded (The HTML is parsed (fastest)), networkidle0 (No network requests for half a second), networkidle2 (At most two network requests for half a second).
Carry on if waiting times outbest_attempttrue/false: Use the page as it is when a wait or the navigation times out, instead of failing the step.Default: false.
Don't loadblock_resourceslist: Optional. Kinds of request to skip, which makes pages load faster. Skipping scripts can stop a page from filling itself in.One or more of: image (Images), media (Video and audio), font (Fonts), stylesheet (Stylesheets), script (Scripts), xhr (XHR requests), fetch (Fetch requests), websocket (WebSockets).
Request headersheadersobject: Optional. Extra HTTP headers to send with every request the page makes, such as Accept-Language.
Stealth modestealthtrue/false: Hide the signs of an automated browser from bot detection. Turn on for sites that block or challenge headless browsers.Default: false.
Proxy networkproxytext: Optional. Route the browser through Browserless's proxies, for sites that block cloud servers. Proxies spend extra units per MB. Leave empty to connect directly.One of: residential (Residential: harder to block), datacenter (Datacenter: cheaper, blocked more often).
Proxy countryproxy_countrytext: Optional. Two-letter code of the country to browse from, such as US, GB or DE, for sites that change by location. Uses the residential proxy unless another network is chosen.
Block adsblock_adstrue/false: Load the page with an ad blocker, so ads and trackers don't load.Default: false.
Sign-in profileprofiletext: Optional. Name of a profile saved in Browserless, so the browser starts signed in with its cookies and storage. 'List profiles' shows the names.
Give up after (seconds)timeout_secondsnumber: Optional. Seconds Browserless may spend on the request before it stops. Your plan sets the default and the most allowed.From 1 to 900.

Outputs

final_urltext: Where the page ended up after any redirects
htmltext: The page's HTML after its scripts ran
status_codenumber: HTTP status the site answered with, or 0
urltext: The page that was loaded, or empty for HTML

Example output

{
  "final_url": "https://example.com/",
  "html": "<!DOCTYPE html><html><head><title>Example Domain</title></head>...</html>",
  "status_code": 200,
  "url": "https://example.com/"
}

Get agent run

Check an agent run: its status, its answer once it finishes, the steps it has taken, and any page captures. While it waits for a person, this gives the live link to finish the step at. Results last 7 days.

Inputs

Run IDrun_idtextRequired: The agent run's ID, from 'Start an agent task' or 'List agent runs'.

Outputs

answertext: The agent's answer, when no answer shape was given
capture_errorsobject: Why a capture asked for is missing, by capture
completed_attext: When it finished, or empty
created_attext: When it started
dataobject: The full result, in the answer shape if given
document_reftext: ID of the stored screenshot, or empty when there is none
documentslist: The screenshot, saved to your workspace's file storage. Empty when none was taken.
errortext: Why it failed, or empty
expires_attext: When the result is deleted, or empty
htmltext: The last page's HTML, if captured
human_requestobject: The hand-off to a person, if one was asked for
is_finishedtrue/false: True once the run has ended, however it ended
linkslist: The last page's links, if captured
markdowntext: The last page as markdown, if captured
needs_humantrue/false: True while it waits for a person
replay_errortext: Why no replay was recorded, or empty
run_idtext: The run's ID
screenshot_urltext: Link that serves the screenshot, or empty
statustext: pending, running, needs_human, succeeded, failed, timed_out or stopped
stepslist: What the agent did, step by step
unitsnumber: Units the agent's model use came to

Example output

{
  "answer": "Example Domain",
  "capture_errors": {},
  "completed_at": "2026-10-15T10:00:18.000Z",
  "created_at": "2026-10-15T10:00:00.000Z",
  "data": {
    "answer": "Example Domain",
    "final_url": "https://example.com",
    "reason_code": "SUCCESS",
    "success": true
  },
  "document_ref": "doc_9f8e7d6c5b4a3210",
  "documents": [
    {
      "content_type": "image/png",
      "document_ref": "doc_9f8e7d6c5b4a3210",
      "filename": "agent-run.png",
      "size_bytes": 40960,
      "url": "/actions/core/serve-document/doc_9f8e7d6c5b4a3210?teamId=6512a1b2c3d4e5f600000001"
    }
  ],
  "error": "",
  "expires_at": "2026-10-22T10:00:18.000Z",
  "html": "",
  "human_request": {
    "expires_at": "",
    "instructions": "",
    "live_url": "",
    "outcome": "",
    "reason": ""
  },
  "is_finished": true,
  "links": [],
  "markdown": "Example Domain\n==============",
  "needs_human": false,
  "replay_error": "",
  "run_id": "run_abc123def456",
  "screenshot_url": "/actions/core/serve-document/doc_9f8e7d6c5b4a3210?teamId=6512a1b2c3d4e5f600000001",
  "status": "succeeded",
  "steps": [
    "Reading the exact page title",
    "Recording the successful title lookup"
  ],
  "units": 4
}

Get crawl

Check a crawl's progress and get its pages, ten at a time, with each page's markdown, HTML or text. Repeat with 'Skip' set to next_skip to get the rest. Results last 24 hours after the crawl finishes.

Inputs

Crawl IDcrawl_idtextRequired: The crawl's ID, from 'Crawl a site' or 'List crawls'.
Skipskipnumber: Optional. How many pages to skip: the next_skip of the previous call.At least 0.
Include page contentinclude_contenttrue/false: Read each finished page's markdown, HTML or text. Turn off to only check progress.Default: true.

Outputs

completednumber: Pages scraped
crawl_idtext: The crawl's ID
expires_attext: When the results are deleted, once finished
failednumber: Pages that failed
is_finishedtrue/false: True once the crawl is no longer running
next_skipnumber: The 'Skip' that gets the next pages, or null when these are the last
pageslist: This batch of pages
statustext: in-progress, completed, failed or cancelled
totalnumber: Pages found so far

Example output

{
  "completed": 15,
  "crawl_id": "crawl_abc123def456",
  "expires_at": "2026-10-16T18:05:00.000Z",
  "failed": 0,
  "is_finished": true,
  "next_skip": 10,
  "pages": [
    {
      "content_error": "",
      "content_url": "https://crawl-artifacts.s3.us-east-1.amazonaws.com/crawls/crawl_abc123def456/page_0a1b2c3d4e5f.json?X-Amz-Signature=...",
      "description": "HTTP endpoints for common browser tasks.",
      "error": "",
      "html": "",
      "language": "en",
      "markdown": "# REST APIs\n\nBrowserless REST APIs provide HTTP endpoints...",
      "raw_text": "",
      "scraped_at": "2026-10-15T18:01:12.000Z",
      "source_url": "https://docs.browserless.io/rest-apis/intro",
      "status": "completed",
      "status_code": 200,
      "title": "REST APIs | Browserless.io"
    }
  ],
  "status": "completed",
  "total": 15
}

Get profile

Look up one saved sign-in profile by name, and whether each of its logins is still valid, about to expire or expired.

Inputs

Profile namenametextRequired: The profile's name, as 'List profiles' shows it.

Outputs

cookie_countnumber: Cookies saved in it
created_attext: When it was created
last_used_attext: When it was last used, or empty
loginslist: Each saved login and whether it is still valid
nametext: The profile's name, which actions take as 'Sign-in profile'
origin_countnumber: Sites whose local storage or IndexedDB it holds
profile_idtext: The profile's ID
updated_attext: When it last changed

Example output

{
  "cookie_count": 38,
  "created_at": "2026-09-01T10:00:00.000Z",
  "last_used_at": "2026-10-14T16:20:00.000Z",
  "logins": [
    {
      "domain": "app.acme.com",
      "expires_at": "2026-11-30T09:00:00.000Z",
      "status": "valid"
    }
  ],
  "name": "acme-prod",
  "origin_count": 3,
  "profile_id": "prof_4f1c2a9e",
  "updated_at": "2026-09-01T10:00:00.000Z"
}

List agent runs

List your account's agent runs, newest first.

Inputs

Statusstatustext: Optional. Only runs in this state.One of: pending, running, needs_human (Waiting for a person), succeeded, failed, timed_out (Timed out), stopped.
Results per pagelimitnumber: Optional. How many to return, from 1 to 100. Browserless returns 20.From 1 to 100.
Next page cursorcursortext: Optional. The next_cursor from an earlier call, to get the next page.

Outputs

next_cursortext: Cursor for the next page, or empty when none
runslist: The runs on this page

Example output

{
  "next_cursor": "",
  "runs": [
    {
      "completed_at": "2026-10-15T10:00:18.000Z",
      "created_at": "2026-10-15T10:00:00.000Z",
      "expires_at": "2026-10-22T10:00:18.000Z",
      "run_id": "run_abc123def456",
      "status": "succeeded",
      "task_preview": "Go to https://news.ycombinator.com and list the titles of the top 3 stories.",
      "units": 2
    }
  ]
}

List crawls

List your account's crawls, newest first, with their progress.

Inputs

Statusstatustext: Optional. Only crawls in this state.One of: in-progress (In progress), completed, failed, cancelled.
Results per pagelimitnumber: Optional. How many to return, from 1 to 100. Browserless returns 20.From 1 to 100.
Next page cursorcursortext: Optional. The next_cursor from an earlier call, to get the next page.

Outputs

crawlslist: The crawls on this page
next_cursortext: Cursor for the next page, or empty when none

Example output

{
  "crawls": [
    {
      "completed": 15,
      "completed_at": "2026-10-15T18:05:00.000Z",
      "crawl_id": "crawl_abc123def456",
      "created_at": "2026-10-15T18:00:00.000Z",
      "status": "completed",
      "total": 15,
      "url": "https://docs.browserless.io"
    }
  ],
  "next_cursor": ""
}

List predefined scrapers

List Browserless's ready-made scrapers (Zillow listings and property details today) and what each call costs. Free to call.

Inputs

None.

Outputs

catalog_versiontext: Version of Browserless's scraper catalog
scraperslist: One row per scraper call

Example output

{
  "catalog_version": "1.2.0",
  "scrapers": [
    {
      "api": "search",
      "cache_seconds": 1800,
      "hostnames": [
        "zillow.com",
        "www.zillow.com"
      ],
      "scraper": "zillow",
      "units": 10
    },
    {
      "api": "property",
      "cache_seconds": 21600,
      "hostnames": [
        "zillow.com",
        "www.zillow.com"
      ],
      "scraper": "zillow",
      "units": 10
    }
  ]
}

List profiles

List the sign-in profiles saved in Browserless (uploaded with its CLI or API), with how many cookies each holds and whether its logins are still valid. Give a profile's name to other actions to browse signed in.

Inputs

At mostlimitnumber: Optional. How many to return, up to 1000. Browserless returns 100.From 1 to 1000.
Skipoffsetnumber: Optional. How many to skip, to page through them.At least 0.

Outputs

profile_countnumber: How many came back
profileslist: The saved profiles

Example output

{
  "profile_count": 1,
  "profiles": [
    {
      "cookie_count": 38,
      "created_at": "2026-09-01T10:00:00.000Z",
      "last_used_at": "2026-10-14T16:20:00.000Z",
      "logins": [
        {
          "domain": "app.acme.com",
          "expires_at": "2026-11-30T09:00:00.000Z",
          "status": "valid"
        }
      ],
      "name": "acme-prod",
      "origin_count": 3,
      "profile_id": "prof_4f1c2a9e",
      "updated_at": "2026-09-01T10:00:00.000Z"
    }
  ]
}

Map a site

List the pages of a site from its sitemap and its links, with titles and descriptions where known. Give a search term to put the most relevant pages first. Cloud plans only.

Inputs

Site URLurltextRequired: The site to start from, starting with http:// or https://.
Most relevant tosearchtext: Optional. Order the pages by how well they match this, such as pricing.
At mostlimitnumber: Optional. The most pages to return, up to 5000.From 1 to 5000.
Sitemapsitemaptext: Optional. How to use the site's sitemap.One of: include (Sitemap and links on the page (default)), only (Only the sitemap), skip (Only links on the page).
Include subdomainsinclude_subdomainstrue/false: Include pages on subdomains, such as blog.example.com.Default: true.
Treat ?query variants as one pageignore_query_parameterstrue/false: Drop the ?query part of addresses, so variants count once.Default: true.
Browse fromcountrytext: Optional. Two-letter code of the country to look from, such as GB, for sites that differ by location.
Proxy networkproxytext: Optional. Route the browser through Browserless's proxies, for sites that block cloud servers. Proxies spend extra units per MB. Leave empty to connect directly.One of: residential (Residential: harder to block), datacenter (Datacenter: cheaper, blocked more often).
Give up after (seconds)timeout_secondsnumber: Optional. Seconds Browserless may spend on the request before it stops. Your plan sets the default and the most allowed.From 1 to 900.

Outputs

link_countnumber: How many pages
linkslist: The pages found
urltext: The site mapped

Example output

{
  "link_count": 2,
  "links": [
    {
      "description": "Simple, transparent pricing for headless browser automation.",
      "title": "Pricing",
      "url": "https://www.browserless.io/pricing"
    },
    {
      "description": "Insights, tips, and updates on headless browser automation.",
      "title": "Blog",
      "url": "https://www.browserless.io/blog"
    }
  ],
  "url": "https://www.browserless.io"
}

Run a BrowserQL query

Run a BrowserQL query: a whole browser session written as GraphQL mutations (go to a page, click, type, solve a captcha, read text) and run in one request. Write and test it in the BrowserQL editor in your Browserless dashboard, then paste it here. Stealth mode suits protected sites.

Inputs

QueryquerytextRequired: The BrowserQL (GraphQL) query to run.
Variablesvariablesobject: Optional. Values for the query's $variables.
Operation nameoperation_nametext: Optional. Which named operation to run, when the query has several.
Stealth modestealthtrue/false: Run on Browserless's stealth browser, which hides that it is automated. Best for bot-protected sites.Default: false.
Proxy networkproxytext: Optional. Route the browser through Browserless's proxies, for sites that block cloud servers. Proxies spend extra units per MB. Leave empty to connect directly.One of: residential (Residential: harder to block), datacenter (Datacenter: cheaper, blocked more often).
Proxy countryproxy_countrytext: Optional. Two-letter code of the country to browse from, such as US, GB or DE, for sites that change by location. Uses the residential proxy unless another network is chosen.
Move like a personhumanliketrue/false: Add human-like mouse movement and typing delays.Default: false.
Hide cookie bannersblock_consent_modalstrue/false: Close cookie-consent banners and pop-ups before the capture.Default: false.
Block adsblock_adstrue/false: Load the page with an ad blocker, so ads and trackers don't load.Default: false.
Sign-in profileprofiletext: Optional. Name of a profile saved in Browserless, so the browser starts signed in with its cookies and storage. 'List profiles' shows the names.
Give up after (seconds)timeout_secondsnumber: Optional. Seconds Browserless may spend on the request before it stops. Your plan sets the default and the most allowed.From 1 to 900.

Outputs

dataobject: What each mutation returned, by its name or alias
errorslist: Errors from mutations that failed, if any

Example output

{
  "data": {
    "goto": {
      "status": 200
    },
    "paragraph": {
      "text": "This domain is for use in documentation examples without needing permission."
    }
  },
  "errors": []
}

Run a Lighthouse audit

Run Google Lighthouse on a page and get its performance, accessibility, best-practices and SEO scores out of 100, its speed metrics (Largest Contentful Paint and others), and the audits it failed with Lighthouse's advice. Takes from several seconds to a few minutes.

Inputs

Page URLurltextRequired: The page to load, starting with http:// or https://.
Categoriescategorieslist: Optional. Which scores to work out. All four if none.One or more of: performance, accessibility, best-practices (Best practices), seo.
Only these auditsauditslist: Optional. Lighthouse audit IDs to run on their own, such as unminified-css or color-contrast. Leave empty to run the categories' audits.
Give up after (seconds)timeout_secondsnumber: Optional. Seconds Browserless may spend on the request before it stops. Your plan sets the default and the most allowed.From 1 to 900.

Outputs

accessibility_scorenumber: Out of 100, or null if not audited
best_practices_scorenumber: Out of 100, or null if not audited
failed_auditslist: Audits scoring under 90, worst first
fetched_attext: When the audit ran (ISO 8601)
final_urltext: Where the page ended up after redirects
lighthouse_versiontext: The Lighthouse version that ran
metricslist: The speed metrics, when performance was audited
performance_scorenumber: Out of 100, or null if not audited
seo_scorenumber: Out of 100, or null if not audited
urltext: The page audited
warningslist: Problems Lighthouse ran into while auditing

Example output

{
  "accessibility_score": 88,
  "best_practices_score": 100,
  "failed_audits": [
    {
      "description": "Low-contrast text is difficult or impossible for many users to read.",
      "display_value": "",
      "id": "color-contrast",
      "score": 0,
      "title": "Background and foreground colors do not have a sufficient contrast ratio."
    }
  ],
  "fetched_at": "2026-10-15T18:02:11.000Z",
  "final_url": "https://example.com/",
  "lighthouse_version": "13.0.3",
  "metrics": [
    {
      "display_value": "1.9 s",
      "id": "largest-contentful-paint",
      "score": 91,
      "title": "Largest Contentful Paint",
      "unit": "millisecond",
      "value": 1912.4
    }
  ],
  "performance_score": 92,
  "seo_score": 90,
  "url": "https://example.com/",
  "warnings": []
}

Run a predefined scraper

Get structured data from a supported site with one of Browserless's ready-made scrapers, at a fixed price per call: search Zillow for homes for sale or rent, or look up a Zillow property. Cloud plans only; in beta at Browserless.

Inputs

ScraperscrapertextRequired: The scraper, as 'List predefined scrapers' names it.
CallapitextRequired: Which of its calls to make, such as search or property.
Inputsscraper_paramsobject: Optional. The call's inputs. For Zillow search: query (such as Austin, TX), tenure (sale or rent), page, sort, priceMin, priceMax, bedsMin and more.
Page URLurltext: Optional. A page on the site instead of inputs, such as a Zillow listing for the property call.
Give up after (seconds)timeout_secondsnumber: Optional. Seconds Browserless may spend on the request before it stops. Your plan sets the default and the most allowed.From 1 to 900.

Outputs

apitext: The call made
dataobject: What it found, in the shape 'List predefined scrapers' describes
scrapertext: The scraper

Example output

{
  "api": "search",
  "data": {
    "page": 1,
    "query": {
      "label": "Austin, TX",
      "tenure": "sale",
      "text": "Austin, TX"
    },
    "results": [
      {
        "baths": 2,
        "beds": 3,
        "price": {
          "amount": 475000,
          "currency": "USD",
          "text": "$475,000"
        },
        "url": "https://www.zillow.com/homedetails/29365471_zpid/",
        "zpid": "29365471"
      }
    ],
    "totalUnits": 5575
  },
  "scraper": "zillow"
}

Run browser code

Run your own Puppeteer code in a Browserless browser, for steps the other actions don't cover: sign in, click through a flow, then return what you found. JSON or text it returns comes back as the result; a file it returns (page.pdf(), a screenshot) is saved to your workspace's file storage.

Inputs

CodecodetextRequired: A JavaScript module whose default export is an async function. It gets { page, context }, where page is a Puppeteer page, and returns { data, type } or a value.
Contextcontextobject: Optional. Values to hand the code as context, such as a URL or a search term from an earlier step.
Stealth modestealthtrue/false: Hide the signs of an automated browser from bot detection. Turn on for sites that block or challenge headless browsers.Default: false.
Proxy networkproxytext: Optional. Route the browser through Browserless's proxies, for sites that block cloud servers. Proxies spend extra units per MB. Leave empty to connect directly.One of: residential (Residential: harder to block), datacenter (Datacenter: cheaper, blocked more often).
Proxy countryproxy_countrytext: Optional. Two-letter code of the country to browse from, such as US, GB or DE, for sites that change by location. Uses the residential proxy unless another network is chosen.
Block adsblock_adstrue/false: Load the page with an ad blocker, so ads and trackers don't load.Default: false.
Sign-in profileprofiletext: Optional. Name of a profile saved in Browserless, so the browser starts signed in with its cookies and storage. 'List profiles' shows the names.
Give up after (seconds)timeout_secondsnumber: Optional. Seconds Browserless may spend on the request before it stops. Your plan sets the default and the most allowed.From 1 to 900.

Outputs

byte_sizenumber: Size of the file the code returned, if any, in bytes
content_typetext: MIME type of the file the code returned, if any,
document_reftext: ID of the stored file the code returned, if any,, for a later step that takes a file
documentslist: The file the code returned, if any,, saved to your workspace's file storage
filenametext: Name the file the code returned, if any, was stored under
result: What the code returned, when it is JSON or text; null when it returned a file
urltext: Link that serves the file the code returned, if any,

Example output

{
  "byte_size": 26,
  "content_type": "application/json",
  "document_ref": "",
  "documents": [],
  "filename": "",
  "result": {
    "title": "Example Domain"
  },
  "url": ""
}

Save a page as PDF

Render a web page in a real browser and print it to PDF, getting past bot protection and captchas when needed. The file is saved to your workspace's file storage; the action returns a document reference and a download URL so a later step can send, upload, or attach it. To set the paper, margins or a header, use 'Convert HTML to PDF'.

Inputs

Page URLurltextRequired: The page to load, starting with http:// or https://.
Proxy networkproxytext: Optional. Which proxy network to route through if the site blocks the first, direct attempt. Leave empty to use Browserless's default (residential).One of: residential (Residential: harder to block), datacenter (Datacenter: cheaper, blocked more often).
Proxy countryproxy_countrytext: Optional. Two-letter code of the country the proxy should exit from, such as US, GB or DE, if the site needs a proxy.
Wait after loading (seconds)wait_secondsnumber: Optional. Seconds to let the page fill itself in after it loads, up to 30. Any wait makes Browserless use a real browser.From 0 to 30.
Do firstbrowser_actionslist: Optional. Up to 20 steps to run in the page before it is read, such as closing a cookie banner or typing a search. Each has a type (wait, click, write, scroll, scrape or executeJavascript) and the fields it needs. Any step makes Browserless use a real browser.
Sign-in profileprofiletext: Optional. Name of a profile saved in Browserless, so the browser starts signed in with its cookies and storage. 'List profiles' shows the names.

Outputs

byte_sizenumber: Size of the PDF in bytes
content_typetext: MIME type of the PDF
document_reftext: ID of the stored PDF, for a later step that takes a file
documentslist: The PDF, saved to your workspace's file storage
filenametext: Name the PDF was stored under
page_urltext: The page that was captured
status_codenumber: HTTP status the page responded with
strategytext: How Browserless fetched the page: http-fetch, http-proxy, browser or browser-captcha
titletext: The page's title
urltext: Link that serves the PDF

Example output

{
  "byte_size": 96256,
  "content_type": "application/pdf",
  "document_ref": "doc_9f8e7d6c5b4a3210",
  "documents": [
    {
      "content_type": "application/pdf",
      "document_ref": "doc_9f8e7d6c5b4a3210",
      "filename": "news-ycombinator-com.pdf",
      "size_bytes": 96256,
      "url": "/actions/core/serve-document/doc_9f8e7d6c5b4a3210?teamId=6512a1b2c3d4e5f600000001"
    }
  ],
  "filename": "news-ycombinator-com.pdf",
  "page_url": "https://news.ycombinator.com/",
  "status_code": 200,
  "strategy": "browser",
  "title": "Hacker News",
  "url": "/actions/core/serve-document/doc_9f8e7d6c5b4a3210?teamId=6512a1b2c3d4e5f600000001"
}

Scrape a page

Fetch a web page and return its HTML, a clean markdown version, its text and its title. Browserless starts with a fast HTTP fetch and escalates to a proxy, a headless browser, or a captcha solve only if the site needs it, so JavaScript-rendered and bot-protected pages work too. Optionally click, type or scroll first, or keep only the parts you need.

Inputs

Page URLurltextRequired: The page to load, starting with http:// or https://.
Proxy networkproxytext: Optional. Which proxy network to route through if the site blocks the first, direct attempt. Leave empty to use Browserless's default (residential).One of: residential (Residential: harder to block), datacenter (Datacenter: cheaper, blocked more often).
Proxy countryproxy_countrytext: Optional. Two-letter code of the country the proxy should exit from, such as US, GB or DE, if the site needs a proxy.
Skip navigation and footersonly_main_contenttrue/false: Leave out navigation, footers, sidebars, scripts and styles. Can't be combined with 'Only these parts'.Default: false.
Only these partsinclude_tagslist: Optional. CSS selectors of the parts to keep, such as article or .price, up to 100. The whole page comes back if none match.
Leave out these partsexclude_tagslist: Optional. CSS selectors of the parts to drop, such as nav or #cookie-banner, up to 100. Can't be combined with 'Only these parts'.
Wait after loading (seconds)wait_secondsnumber: Optional. Seconds to let the page fill itself in after it loads, up to 30. Any wait makes Browserless use a real browser.From 0 to 30.
Request headersheadersobject: Optional. Extra HTTP headers to send to the site, such as Accept-Language. Browserless drops cookie, authorization and forwarding headers.
Do firstbrowser_actionslist: Optional. Up to 20 steps to run in the page before it is read, such as closing a cookie banner or typing a search. Each has a type (wait, click, write, scroll, scrape or executeJavascript) and the fields it needs. Any step makes Browserless use a real browser.
Sign-in profileprofiletext: Optional. Name of a profile saved in Browserless, so the browser starts signed in with its cookies and storage. 'List profiles' shows the names.

Outputs

attemptedlist: Every strategy tried, in order
contenttext: The page's HTML. If the URL answers with JSON instead, this is that JSON as a string; for a PDF, its text.
content_typetext: Content type the page was served with
descriptiontext: The page's meta description
languagetext: The page's language, such as en
markdowntext: The page as markdown, with scripts, styles, and hidden elements stripped
raw_texttext: The page's text, whitespace collapsed
response_headersobject: HTTP headers the site answered with
script_resultslist: What each 'executeJavascript' browser action returned
snapshotslist: What each 'scrape' browser action saw
status_codenumber: HTTP status the page responded with
strategytext: How Browserless fetched the page: http-fetch, http-proxy, browser or browser-captcha
titletext: The page's title
urltext: The page that was scraped

Example output

{
  "attempted": [
    "http-fetch",
    "browser"
  ],
  "content": "<html lang=\"en\" op=\"news\"><head>...</head></html>",
  "content_type": "text/html; charset=utf-8",
  "description": "",
  "language": "en",
  "markdown": "# Hacker News\n\n1. [Motorola GrapheneOS devices...](...)",
  "raw_text": "Hacker News new | past | comments | ask | show | jobs",
  "response_headers": {
    "content-type": "text/html; charset=utf-8"
  },
  "script_results": [
    {
      "type": "number",
      "value": 30
    }
  ],
  "snapshots": [
    {
      "html": "<html>...</html>",
      "url": "https://news.ycombinator.com/news?p=2"
    }
  ],
  "status_code": 200,
  "strategy": "browser",
  "title": "Hacker News",
  "url": "https://news.ycombinator.com/"
}

Scrape elements by CSS selector

Load a page in a real browser and pull out the elements matching each CSS selector you give: their text, HTML, attributes and position. Good for prices, headlines, table cells and other values a page shows in a predictable place.

Inputs

Page URLurltext: The page to load, starting with http:// or https://. Leave empty to render the HTML instead.
CSS selectorsselectorslistRequired: One or more CSS selectors, such as h1, .price or table tr td:first-child. Every match of each comes back.
HTMLhtmltext: HTML to render instead of loading a page, with any CSS in <style> tags. Fill in either this or the page URL.
Wait for elementwait_for_selectortext: Optional. CSS selector of an element to wait for before reading the page, such as #results or .price. The step fails if it never appears, unless 'Carry on if waiting times out' is on.
Wait after loading (seconds)wait_secondsnumber: Optional. Seconds to let the page fill itself in after it loads, up to 30.From 0 to 30.
Page counts as loaded whenwait_untiltext: Optional. When navigation is done. Browserless's default is Load.One of: load (Load: everything, images included, has loaded), domcontentloaded (The HTML is parsed (fastest)), networkidle0 (No network requests for half a second), networkidle2 (At most two network requests for half a second).
Carry on if waiting times outbest_attempttrue/false: Use the page as it is when a wait or the navigation times out, instead of failing the step.Default: false.
Don't loadblock_resourceslist: Optional. Kinds of request to skip, which makes pages load faster. Skipping scripts can stop a page from filling itself in.One or more of: image (Images), media (Video and audio), font (Fonts), stylesheet (Stylesheets), script (Scripts), xhr (XHR requests), fetch (Fetch requests), websocket (WebSockets).
Request headersheadersobject: Optional. Extra HTTP headers to send with every request the page makes, such as Accept-Language.
Stealth modestealthtrue/false: Hide the signs of an automated browser from bot detection. Turn on for sites that block or challenge headless browsers.Default: false.
Proxy networkproxytext: Optional. Route the browser through Browserless's proxies, for sites that block cloud servers. Proxies spend extra units per MB. Leave empty to connect directly.One of: residential (Residential: harder to block), datacenter (Datacenter: cheaper, blocked more often).
Proxy countryproxy_countrytext: Optional. Two-letter code of the country to browse from, such as US, GB or DE, for sites that change by location. Uses the residential proxy unless another network is chosen.
Block adsblock_adstrue/false: Load the page with an ad blocker, so ads and trackers don't load.Default: false.
Sign-in profileprofiletext: Optional. Name of a profile saved in Browserless, so the browser starts signed in with its cookies and storage. 'List profiles' shows the names.
Give up after (seconds)timeout_secondsnumber: Optional. Seconds Browserless may spend on the request before it stops. Your plan sets the default and the most allowed.From 1 to 900.

Outputs

resultslist: One entry per selector, in the order given
urltext: The page that was loaded, or empty for HTML

Example output

{
  "results": [
    {
      "match_count": 2,
      "matches": [
        {
          "attributes": {
            "href": "https://grapheneos.social/..."
          },
          "height": 14,
          "html": "Motorola GrapheneOS devices will be bootloader unlockable",
          "left": 40,
          "text": "Motorola GrapheneOS devices will be bootloader unlockable",
          "top": 72,
          "width": 412
        },
        {
          "attributes": {
            "href": "https://github.com/..."
          },
          "height": 14,
          "html": "Show HN: A tiny SQLite browser",
          "left": 40,
          "text": "Show HN: A tiny SQLite browser",
          "top": 112,
          "width": 228
        }
      ],
      "selector": ".titleline > a",
      "text": "Motorola GrapheneOS devices will be bootloader unlockable",
      "texts": [
        "Motorola GrapheneOS devices will be bootloader unlockable",
        "Show HN: A tiny SQLite browser"
      ]
    }
  ],
  "url": "https://news.ycombinator.com/"
}

Screenshot a page

Render a web page in a real browser and capture the full page as a PNG, getting past bot protection and captchas when needed. The image is saved to your workspace's file storage; the action returns a document reference and a download URL so a later step can send, upload, or attach it.

Inputs

Page URLurltextRequired: The page to load, starting with http:// or https://.
Proxy networkproxytext: Optional. Which proxy network to route through if the site blocks the first, direct attempt. Leave empty to use Browserless's default (residential).One of: residential (Residential: harder to block), datacenter (Datacenter: cheaper, blocked more often).
Proxy countryproxy_countrytext: Optional. Two-letter code of the country the proxy should exit from, such as US, GB or DE, if the site needs a proxy.
Wait after loading (seconds)wait_secondsnumber: Optional. Seconds to let the page fill itself in after it loads, up to 30. Any wait makes Browserless use a real browser.From 0 to 30.
Do firstbrowser_actionslist: Optional. Up to 20 steps to run in the page before it is read, such as closing a cookie banner or typing a search. Each has a type (wait, click, write, scroll, scrape or executeJavascript) and the fields it needs. Any step makes Browserless use a real browser.
Sign-in profileprofiletext: Optional. Name of a profile saved in Browserless, so the browser starts signed in with its cookies and storage. 'List profiles' shows the names.

Outputs

byte_sizenumber: Size of the screenshot in bytes
content_typetext: MIME type of the screenshot
document_reftext: ID of the stored screenshot, for a later step that takes a file
documentslist: The screenshot, saved to your workspace's file storage
filenametext: Name the screenshot was stored under
page_urltext: The page that was captured
status_codenumber: HTTP status the page responded with
strategytext: How Browserless fetched the page: http-fetch, http-proxy, browser or browser-captcha
titletext: The page's title
urltext: Link that serves the screenshot

Example output

{
  "byte_size": 184320,
  "content_type": "image/png",
  "document_ref": "doc_9f8e7d6c5b4a3210",
  "documents": [
    {
      "content_type": "image/png",
      "document_ref": "doc_9f8e7d6c5b4a3210",
      "filename": "news-ycombinator-com.png",
      "size_bytes": 184320,
      "url": "/actions/core/serve-document/doc_9f8e7d6c5b4a3210?teamId=6512a1b2c3d4e5f600000001"
    }
  ],
  "filename": "news-ycombinator-com.png",
  "page_url": "https://news.ycombinator.com/",
  "status_code": 200,
  "strategy": "browser",
  "title": "Hacker News",
  "url": "/actions/core/serve-document/doc_9f8e7d6c5b4a3210?teamId=6512a1b2c3d4e5f600000001"
}

Search the web

Search the web, news or images, filtered by language, country, date or kind of site, and optionally read each result page as markdown or HTML in the same step. Your plan caps the results (3 on the free plan). Cloud plans only; in beta at Browserless.

Inputs

Search forquerytextRequired: What to search for.
Resultslimitnumber: Optional. Results per source, up to your plan's cap (Free 3, Prototyping 5, Starter 10, Scale 20).From 1 to 20.
Search insourceslist: Optional. The web unless chosen otherwise.One or more of: web, news, images.
Languagelangtext: Optional. Language code of the results, such as en or de.
Search fromcountrytext: Optional. Two-letter country code, such as US or GB.
Search nearlocationtext: Optional. A place for local results, such as San Francisco.
From the pasttime_rangetext: Optional. Only results from this recent period.One of: day, week, month, year.
Only these kinds of sitecategorieslist: Optional. Narrow web results to these.One or more of: github (GitHub repositories), research (Research papers), pdf (PDF documents).
Also read each result asscrape_formatslist: Optional. Read every result page in the same step and return it in these forms. Costs more units.One or more of: markdown, html, links.
Only the articleonly_main_contenttrue/false: When reading result pages, keep only each page's main article.Default: false.
Proxy networkproxytext: Optional. Route the browser through Browserless's proxies, for sites that block cloud servers. Proxies spend extra units per MB. Leave empty to connect directly.One of: residential (Residential: harder to block), datacenter (Datacenter: cheaper, blocked more often).
Give up after (seconds)timeout_secondsnumber: Optional. Seconds Browserless may spend on the request before it stops. Your plan sets the default and the most allowed.From 1 to 900.

Outputs

imageslist: Image results, when images were searched
newslist: News results, when news was searched
querytext: What was searched for
total_resultsnumber: How many results came back in all
weblist: Web results

Example output

{
  "images": [],
  "news": [],
  "query": "headless browser automation",
  "total_results": 1,
  "web": [
    {
      "date": "",
      "description": "Headless browser automation, without the hosting headaches.",
      "html": "",
      "image_url": "",
      "links": [],
      "markdown": "",
      "position": 1,
      "scrape_error": "",
      "title": "Browserless - Headless Browser Automation",
      "url": "https://www.browserless.io/"
    }
  ]
}

Start an agent task

Describe a task in plain English and Browserless's managed AI agent does it in a real browser: navigating, clicking, typing and reading. It works in the background; follow it with 'Get agent run' until it finishes. Ask for a JSON shape to get structured data back. Cloud plans only; in beta at Browserless.

Inputs

TasktasktextRequired: What the agent should do, at least 10 characters, such as 'Find the price of the Pro plan on browserless.io'.
Start atstart_urltext: Optional. The page the agent opens first.
Only these sitesallowed_domainslist: Optional. Domains the agent may visit, such as browserless.io.
Most browser stepsmax_stepsnumber: Optional. A soft cap on how many browser actions the agent may take. Browserless sets the default and limit.From 1 to 90.
Give up after (minutes)timeout_minutesnumber: Optional. Up to 15, which is the default.From 0.5 to 15.
Answer shaperesponse_schemaobject: Optional. A JSON Schema for the answer, so 'data' comes back in that shape. Best effort, so check the result.
Capture the last page aspage_captureslist: Optional. Save the agent's final page in these forms. The screenshot is of the visible window.One or more of: markdown, html, links, screenshot.
Proxy networkproxytext: Optional. Route the browser through Browserless's proxies, for sites that block cloud servers. Proxies spend extra units per MB. Leave empty to connect directly.One of: residential (Residential: harder to block), datacenter (Datacenter: cheaper, blocked more often).
Proxy countryproxy_countrytext: Optional. Two-letter code of the country to browse from, such as US, GB or DE, for sites that change by location. Uses the residential proxy unless another network is chosen.
Stealth modestealthtrue/false: Hide the signs of an automated browser from bot detection. Turn on for sites that block or challenge headless browsers.Default: false.
Solve captchassolve_captchastrue/false: Let the agent solve captchas it meets.Default: false.
Sign-in profileprofiletext: Optional. Name of a profile saved in Browserless, so the browser starts signed in with its cookies and storage. 'List profiles' shows the names.
Pause for a person at sign-inspause_for_humantrue/false: At a login wall or two-step check, pause and give a live link for a person to finish it, instead of failing. The time limit keeps running.Default: false.
Record a replayrecord_replaytrue/false: Record the session for Session Replay in your Browserless dashboard.Default: false.
Webhook URLwebhook_urltext: Optional. An https:// address Browserless calls when the job finishes, such as a Lodol webhook trigger.
Call the webhook whenwebhook_eventslist: Optional. Which events to send. Success and failure if none.One or more of: succeeded (The run succeeds), failed (The run fails, times out or is stopped), needs_human (The run pauses for a person).

Outputs

run_idtext: The run's ID, for 'Get agent run'
statustext: pending

Example output

{
  "run_id": "run_abc123def456",
  "status": "pending"
}

Take a custom screenshot

Screenshot a page, or HTML of your own, with the details chosen: PNG, JPEG or WebP, the window size, the whole page or just what fits, or one element on it. The image is saved to your workspace's file storage. Unlike 'Screenshot a page', it doesn't fall back to a captcha solve, so turn on stealth or a proxy for protected sites.

Inputs

Page URLurltext: The page to load, starting with http:// or https://. Leave empty to render the HTML instead.
HTMLhtmltext: HTML to render instead of loading a page, with any CSS in <style> tags. Fill in either this or the page URL.
Image formatimage_formattext: Optional. PNG unless chosen otherwise.One of: png (PNG: sharp, larger files), jpeg (JPEG: smaller files, no transparency), webp (WebP: smallest files).
Qualityqualitynumber: Optional. Image quality from 0 to 100.Only when Image format is JPEG: smaller files, no transparency or WebP: smallest files. From 0 to 100.
Whole pagefull_pagetrue/false: Capture the whole page, scrolled top to bottom. Turn off for just the visible window.Default: true.
Only this elementselectortext: Optional. CSS selector of one element to capture, cropped to its edges, such as #chart.
Window width (px)viewport_widthnumber: Optional. Browser window width; give the height too.From 1 to 8000.
Window height (px)viewport_heightnumber: Optional. Browser window height; give the width too.From 1 to 8000.
Pixel densitydevice_scale_factornumber: Optional. 2 for a sharp, retina-style image. Needs a window width and height.From 0.1 to 4.
Transparent backgroundomit_backgroundtrue/false: Leave out the page's default white background, for a PNG or WebP with transparency.Default: false.
Scroll through firstscroll_pagetrue/false: Scroll down the page before capturing, so images that load as you scroll are in the shot.Default: false.
Hide cookie bannersblock_consent_modalstrue/false: Close cookie-consent banners and pop-ups before the capture.Default: false.
Wait for elementwait_for_selectortext: Optional. CSS selector of an element to wait for before reading the page, such as #results or .price. The step fails if it never appears, unless 'Carry on if waiting times out' is on.
Wait after loading (seconds)wait_secondsnumber: Optional. Seconds to let the page fill itself in after it loads, up to 30.From 0 to 30.
Page counts as loaded whenwait_untiltext: Optional. When navigation is done. Browserless's default is Load.One of: load (Load: everything, images included, has loaded), domcontentloaded (The HTML is parsed (fastest)), networkidle0 (No network requests for half a second), networkidle2 (At most two network requests for half a second).
Carry on if waiting times outbest_attempttrue/false: Use the page as it is when a wait or the navigation times out, instead of failing the step.Default: false.
Stealth modestealthtrue/false: Hide the signs of an automated browser from bot detection. Turn on for sites that block or challenge headless browsers.Default: false.
Proxy networkproxytext: Optional. Route the browser through Browserless's proxies, for sites that block cloud servers. Proxies spend extra units per MB. Leave empty to connect directly.One of: residential (Residential: harder to block), datacenter (Datacenter: cheaper, blocked more often).
Proxy countryproxy_countrytext: Optional. Two-letter code of the country to browse from, such as US, GB or DE, for sites that change by location. Uses the residential proxy unless another network is chosen.
Block adsblock_adstrue/false: Load the page with an ad blocker, so ads and trackers don't load.Default: false.
Sign-in profileprofiletext: Optional. Name of a profile saved in Browserless, so the browser starts signed in with its cookies and storage. 'List profiles' shows the names.
Give up after (seconds)timeout_secondsnumber: Optional. Seconds Browserless may spend on the request before it stops. Your plan sets the default and the most allowed.From 1 to 900.
File namefilenametext: Optional. Name to store the file under. Leave empty to name it after the page.

Outputs

byte_sizenumber: Size of the screenshot in bytes
content_typetext: MIME type of the screenshot
document_reftext: ID of the stored screenshot, for a later step that takes a file
documentslist: The screenshot, saved to your workspace's file storage
filenametext: Name the screenshot was stored under
final_urltext: Where the page ended up after any redirects
page_urltext: The page that was loaded, or empty for rendered HTML
status_codenumber: HTTP status the site answered with, or 0 for rendered HTML
urltext: Link that serves the screenshot

Example output

{
  "byte_size": 48211,
  "content_type": "image/webp",
  "document_ref": "doc_9f8e7d6c5b4a3210",
  "documents": [
    {
      "content_type": "image/webp",
      "document_ref": "doc_9f8e7d6c5b4a3210",
      "filename": "example-com.webp",
      "size_bytes": 48211,
      "url": "/actions/core/serve-document/doc_9f8e7d6c5b4a3210?teamId=6512a1b2c3d4e5f600000001"
    }
  ],
  "filename": "example-com.webp",
  "final_url": "https://example.com/",
  "page_url": "https://example.com/",
  "status_code": 200,
  "url": "/actions/core/serve-document/doc_9f8e7d6c5b4a3210?teamId=6512a1b2c3d4e5f600000001"
}

Unblock a page

Get past a site's bot detection (Cloudflare, DataDome and passive captchas) and return the page's HTML, the cookies it set, a screenshot, or all three. Pass the cookies to later requests to keep the session the site trusts.

Inputs

Page URLurltextRequired: The page to load, starting with http:// or https://.
Return the HTMLreturn_htmltrue/false: Return the page's HTML once it is unblocked.Default: true.
Return the cookiesreturn_cookiestrue/false: Return the cookies the site set.Default: true.
Take a screenshotreturn_screenshottrue/false: Also save a full-page JPEG of the unblocked page.Default: false.
Proxy networkproxytext: Optional. Unblocking works best through the residential proxy, which is used unless you choose otherwise. Proxies spend extra units per MB.One of: residential (Residential: hardest to block), datacenter (Datacenter: cheaper, blocked more often), none (No proxy). Default: residential.
Proxy countryproxy_countrytext: Optional. Two-letter code of the country to browse from, such as US, GB or DE, for sites that change by location. Uses the residential proxy unless another network is chosen.
Solve captchassolve_captchastrue/false: Solve a captcha that stands in the way. Each solve spends extra units.Default: false.
Wait for elementwait_for_selectortext: Optional. CSS selector of an element to wait for before reading the page, such as #results or .price. The step fails if it never appears, unless 'Carry on if waiting times out' is on.
Wait after loading (seconds)wait_secondsnumber: Optional. Seconds to let the page fill itself in after it loads, up to 30.From 0 to 30.
Page counts as loaded whenwait_untiltext: Optional. When navigation is done. Browserless's default is Load.One of: load (Load: everything, images included, has loaded), domcontentloaded (The HTML is parsed (fastest)), networkidle0 (No network requests for half a second), networkidle2 (At most two network requests for half a second).
Carry on if waiting times outbest_attempttrue/false: Use the page as it is when a wait or the navigation times out, instead of failing the step.Default: false.
Give up after (seconds)timeout_secondsnumber: Optional. Seconds Browserless may spend on the request before it stops. Your plan sets the default and the most allowed.From 1 to 900.

Outputs

challenge_solvedtrue/false: True when Browserless found a bot challenge and solved it
cookieslist: The cookies the site set, if asked for
document_reftext: ID of the stored screenshot, or empty when there is none
documentslist: The screenshot, saved to your workspace's file storage. Empty when none was taken.
htmltext: The page's HTML, or empty if not asked for
screenshot_urltext: Link that serves the screenshot, or empty
urltext: The page that was unblocked

Example output

{
  "challenge_solved": true,
  "cookies": [
    {
      "domain": "www.example-shop.com",
      "expires": 1792000000,
      "http_only": true,
      "name": "session_id",
      "path": "/",
      "same_site": "Lax",
      "secure": true,
      "value": "XYZ123"
    }
  ],
  "document_ref": "doc_9f8e7d6c5b4a3210",
  "documents": [
    {
      "content_type": "image/jpeg",
      "document_ref": "doc_9f8e7d6c5b4a3210",
      "filename": "www-example-shop-com.jpg",
      "size_bytes": 61210,
      "url": "/actions/core/serve-document/doc_9f8e7d6c5b4a3210?teamId=6512a1b2c3d4e5f600000001"
    }
  ],
  "html": "<!DOCTYPE html><html>...</html>",
  "screenshot_url": "/actions/core/serve-document/doc_9f8e7d6c5b4a3210?teamId=6512a1b2c3d4e5f600000001",
  "url": "https://www.example-shop.com/"
}

ActionsCopy Anchor Link

Cancel crawlCopy Anchor Link

Inputs

Outputs

Cancel or delete agent runCopy Anchor Link

Inputs

Outputs

Convert HTML to PDFCopy Anchor Link

Inputs

Outputs

Crawl a siteCopy Anchor Link

Inputs

Outputs

Download a file with browser codeCopy Anchor Link

Inputs

Outputs

Export a URL as a fileCopy Anchor Link

Inputs

Outputs

Extract links from a pageCopy Anchor Link

Inputs

Outputs

Get a page's rendered HTMLCopy Anchor Link

Inputs

Outputs

Get agent runCopy Anchor Link

Inputs

Outputs

Get crawlCopy Anchor Link

Inputs

Outputs

Get profileCopy Anchor Link

Inputs

Outputs

List agent runsCopy Anchor Link

Inputs

Outputs

List crawlsCopy Anchor Link

Inputs

Outputs

List predefined scrapersCopy Anchor Link

Inputs

Outputs

List profilesCopy Anchor Link

Inputs

Outputs

Map a siteCopy Anchor Link

Inputs

Outputs

Run a BrowserQL queryCopy Anchor Link

Inputs

Outputs

Run a Lighthouse auditCopy Anchor Link

Inputs

Outputs

Run a predefined scraperCopy Anchor Link

Inputs

Outputs

Run browser codeCopy Anchor Link

Inputs

Outputs

Save a page as PDFCopy Anchor Link

Inputs

Outputs

Scrape a pageCopy Anchor Link

Inputs

Outputs

Scrape elements by CSS selectorCopy Anchor Link

Inputs

Outputs

Screenshot a pageCopy Anchor Link

Inputs

Outputs

Search the webCopy Anchor Link

Inputs

Outputs

Start an agent taskCopy Anchor Link

Inputs

Outputs

Actions

Cancel crawl

Cancel or delete agent run

Convert HTML to PDF

Crawl a site

Download a file with browser code

Export a URL as a file

Extract links from a page

Get a page's rendered HTML

Get agent run

Get crawl

Get profile

List agent runs

List crawls

List predefined scrapers

List profiles

Map a site

Run a BrowserQL query

Run a Lighthouse audit

Run a predefined scraper

Run browser code

Save a page as PDF

Scrape a page

Scrape elements by CSS selector

Screenshot a page

Search the web

Start an agent task

Take a custom screenshot

Unblock a page