# 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.

App · AI Agents · 28 actions. Web page: https://docs.lodol.com/docs/integrations/browserless

## Actions

### Cancel crawl

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

**Inputs**

- Crawl ID (`crawl_id`, text, required): The crawl's ID, from 'Crawl a site' or 'List crawls'.

**Outputs**

- `crawl_id` (text): The crawl's ID
- `status` (text): cancelled

**Example output**

```json
{
  "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 ID (`run_id`, text, required): The agent run's ID, from 'Start an agent task' or 'List agent runs'.

**Outputs**

- `run_id` (text): The run's ID
- `status` (text): stopped or deleted

**Example output**

```json
{
  "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**

- HTML (`html`, text): The HTML to print, with any CSS in <style> tags. Fill in either this or the page URL.
- Page URL (`url`, text): A page to print instead, starting with http:// or https://. Leave empty when printing HTML.
- Paper size (`paper_format`, text): 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`.
- Landscape (`landscape`, true/false): Print sideways. Default: `false`.
- Print backgrounds (`print_background`, true/false): Print background colours and images, as the page shows them on screen. Default: `true`.
- Margins (`margin`, text): Optional. One margin for all four sides, such as 1cm, 0.5in or 20px.
- Scale (`scale`, number): Optional. Zoom from 0.1 to 2; 1 is actual size. From 0.1 to 2.
- Pages (`page_ranges`, text): Optional. Which pages to keep, such as 1-5, 8, 11-13.
- Header (`header_template`, text): 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.
- Footer (`footer_template`, text): Optional. HTML for the bottom of every page, filled in the same way as the header.
- Use the page size in the CSS (`prefer_css_page_size`, true/false): Use a size set by an @page rule in the HTML over the paper size. Default: `false`.
- Accessible PDF (`tagged`, true/false): Tag the PDF with the HTML's structure (headings, reading order) for screen readers and parsers. Default: `false`.
- Bookmarks (`outline`, true/false): Add bookmarks built from the HTML's headings. Default: `false`.
- Styles to use (`media_type`, text): 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 banners (`block_consent_modals`, true/false): Close cookie-consent banners and pop-ups before the capture. Default: `false`.
- Wait for element (`wait_for_selector`, text): 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_seconds`, number): Optional. Seconds to let the page fill itself in after it loads, up to 30. From 0 to 30.
- Page counts as loaded when (`wait_until`, text): 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 out (`best_attempt`, true/false): Use the page as it is when a wait or the navigation times out, instead of failing the step. Default: `false`.
- Stealth mode (`stealth`, true/false): Hide the signs of an automated browser from bot detection. Turn on for sites that block or challenge headless browsers. Default: `false`.
- Proxy network (`proxy`, text): 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 country (`proxy_country`, text): 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 ads (`block_ads`, true/false): Load the page with an ad blocker, so ads and trackers don't load. Default: `false`.
- Sign-in profile (`profile`, text): 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_seconds`, number): 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 name (`filename`, text): Optional. Name to store the PDF under, such as invoice-1042.pdf. Leave empty to name it after the page.

**Outputs**

- `byte_size` (number): Size of the PDF in bytes
- `content_type` (text): MIME type of the PDF
- `document_ref` (text): ID of the stored PDF, for a later step that takes a file
- `documents` (list): The PDF, saved to your workspace's file storage
- `filename` (text): Name the PDF was stored under
- `final_url` (text): Where the page ended up after any redirects
- `page_url` (text): The page that was loaded, or empty for rendered HTML
- `status_code` (number): HTTP status the site answered with, or 0 for rendered HTML
- `url` (text): Link that serves the PDF

**Example output**

```json
{
  "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 URL (`url`, text, required): The site to start from, starting with http:// or https://.
- At most (`limit`, number): Optional. The most pages to crawl. Browserless crawls 100, and your plan sets the most. From 1 to 10000.
- Links deep (`max_depth`, number): Optional. How many links away from the start page to go, 0 to 20. Browserless goes 5. From 0 to 20.
- Follow links to subdomains (`allow_subdomains`, true/false): Also crawl subdomains, such as blog.example.com. Default: `false`.
- Follow links to other sites (`allow_external_links`, true/false): Also crawl pages on other domains the site links to. Default: `false`.
- Sitemap (`sitemap`, text): 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 matching (`include_paths`, list): Optional. Regular expressions a page's path must match, such as ^/blog.
- Skip paths matching (`exclude_paths`, list): Optional. Regular expressions of paths to skip, such as ^/blog/tag.
- Bring back (`formats`, list): Optional. What each page comes back as; markdown if none. One or more of: `markdown`, `html`, `rawText` (Text).
- Skip navigation and footers (`only_main_content`, true/false): Keep only each page's main content. On unless turned off. Default: `true`.
- Wait after loading (seconds) (`wait_seconds`, number): Optional. Seconds to let the page fill itself in after it loads, up to 30. From 0 to 30.
- Proxy network (`proxy`, text): 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 URL (`webhook_url`, text): Optional. An https:// address Browserless calls when the job finishes, such as a Lodol webhook trigger.
- Call the webhook when (`webhook_events`, list): 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 profile (`profile`, text): 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_id` (text): The crawl's ID, for 'Get crawl'
- `url` (text): Where the crawl starts

**Example output**

```json
{
  "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**

- Code (`code`, text, required): 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.
- Context (`context`, object): Optional. Values to hand the code as context, such as a URL or a search term from an earlier step.
- Stealth mode (`stealth`, true/false): Hide the signs of an automated browser from bot detection. Turn on for sites that block or challenge headless browsers. Default: `false`.
- Proxy network (`proxy`, text): 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 country (`proxy_country`, text): 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 ads (`block_ads`, true/false): Load the page with an ad blocker, so ads and trackers don't load. Default: `false`.
- Sign-in profile (`profile`, text): 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_seconds`, number): 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 name (`filename`, text): 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_size` (number): Size of the downloaded file in bytes
- `content_type` (text): MIME type of the downloaded file
- `document_ref` (text): ID of the stored downloaded file, for a later step that takes a file
- `documents` (list): The downloaded file, saved to your workspace's file storage
- `filename` (text): Name the downloaded file was stored under
- `url` (text): Link that serves the downloaded file

**Example output**

```json
{
  "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 URL (`url`, text, required): The page to load, starting with http:// or https://.
- Zip with images and styles (`include_resources`, true/false): Save a zip of the page's HTML with every image, stylesheet and script it uses. Default: `false`.
- Wait for element (`wait_for_selector`, text): 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_seconds`, number): Optional. Seconds to let the page fill itself in after it loads, up to 30. From 0 to 30.
- Page counts as loaded when (`wait_until`, text): 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 out (`best_attempt`, true/false): Use the page as it is when a wait or the navigation times out, instead of failing the step. Default: `false`.
- Request headers (`headers`, object): Optional. Extra HTTP headers to send with every request the page makes, such as Accept-Language.
- Stealth mode (`stealth`, true/false): Hide the signs of an automated browser from bot detection. Turn on for sites that block or challenge headless browsers. Default: `false`.
- Proxy network (`proxy`, text): 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 country (`proxy_country`, text): 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 ads (`block_ads`, true/false): Load the page with an ad blocker, so ads and trackers don't load. Default: `false`.
- Sign-in profile (`profile`, text): 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_seconds`, number): 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 name (`filename`, text): Optional. Name to store the file under. Leave empty to name it after the page.

**Outputs**

- `byte_size` (number): Size of the file in bytes
- `content_type` (text): MIME type of the file
- `document_ref` (text): ID of the stored file, for a later step that takes a file
- `documents` (list): The file, saved to your workspace's file storage
- `filename` (text): Name the file was stored under
- `final_url` (text): Where the URL ended up after any redirects
- `page_url` (text): The URL exported
- `status_code` (number): HTTP status the site answered with, or 0
- `url` (text): Link that serves the file

**Example output**

```json
{
  "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 URL (`url`, text, required): The page to load, starting with http:// or https://.
- Proxy network (`proxy`, text): 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 country (`proxy_country`, text): 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 footers (`only_main_content`, true/false): Leave out navigation, footers, sidebars, scripts and styles. Can't be combined with 'Only these parts'. Default: `false`.
- Only these parts (`include_tags`, list): 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 parts (`exclude_tags`, list): 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_seconds`, number): 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 first (`browser_actions`, list): 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 profile (`profile`, text): 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**

- `links` (list): Every http(s) link on the page, as absolute URLs
- `status_code` (number): HTTP status the page responded with
- `strategy` (text): How Browserless fetched the page: http-fetch, http-proxy, browser or browser-captcha
- `title` (text): The page's title
- `url` (text): The page that was read

**Example output**

```json
{
  "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 URL (`url`, text): The page to load, starting with http:// or https://. Leave empty to render the HTML instead.
- HTML (`html`, text): HTML to render instead of loading a page, with any CSS in <style> tags. Fill in either this or the page URL.
- Wait for element (`wait_for_selector`, text): 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_seconds`, number): Optional. Seconds to let the page fill itself in after it loads, up to 30. From 0 to 30.
- Page counts as loaded when (`wait_until`, text): 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 out (`best_attempt`, true/false): Use the page as it is when a wait or the navigation times out, instead of failing the step. Default: `false`.
- Don't load (`block_resources`, list): 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 headers (`headers`, object): Optional. Extra HTTP headers to send with every request the page makes, such as Accept-Language.
- Stealth mode (`stealth`, true/false): Hide the signs of an automated browser from bot detection. Turn on for sites that block or challenge headless browsers. Default: `false`.
- Proxy network (`proxy`, text): 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 country (`proxy_country`, text): 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 ads (`block_ads`, true/false): Load the page with an ad blocker, so ads and trackers don't load. Default: `false`.
- Sign-in profile (`profile`, text): 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_seconds`, number): 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_url` (text): Where the page ended up after any redirects
- `html` (text): The page's HTML after its scripts ran
- `status_code` (number): HTTP status the site answered with, or 0
- `url` (text): The page that was loaded, or empty for HTML

**Example output**

```json
{
  "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 ID (`run_id`, text, required): The agent run's ID, from 'Start an agent task' or 'List agent runs'.

**Outputs**

- `answer` (text): The agent's answer, when no answer shape was given
- `capture_errors` (object): Why a capture asked for is missing, by capture
- `completed_at` (text): When it finished, or empty
- `created_at` (text): When it started
- `data` (object): The full result, in the answer shape if given
- `document_ref` (text): ID of the stored screenshot, or empty when there is none
- `documents` (list): The screenshot, saved to your workspace's file storage. Empty when none was taken.
- `error` (text): Why it failed, or empty
- `expires_at` (text): When the result is deleted, or empty
- `html` (text): The last page's HTML, if captured
- `human_request` (object): The hand-off to a person, if one was asked for
- `is_finished` (true/false): True once the run has ended, however it ended
- `links` (list): The last page's links, if captured
- `markdown` (text): The last page as markdown, if captured
- `needs_human` (true/false): True while it waits for a person
- `replay_error` (text): Why no replay was recorded, or empty
- `run_id` (text): The run's ID
- `screenshot_url` (text): Link that serves the screenshot, or empty
- `status` (text): pending, running, needs_human, succeeded, failed, timed_out or stopped
- `steps` (list): What the agent did, step by step
- `units` (number): Units the agent's model use came to

**Example output**

```json
{
  "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 ID (`crawl_id`, text, required): The crawl's ID, from 'Crawl a site' or 'List crawls'.
- Skip (`skip`, number): Optional. How many pages to skip: the next_skip of the previous call. At least 0.
- Include page content (`include_content`, true/false): Read each finished page's markdown, HTML or text. Turn off to only check progress. Default: `true`.

**Outputs**

- `completed` (number): Pages scraped
- `crawl_id` (text): The crawl's ID
- `expires_at` (text): When the results are deleted, once finished
- `failed` (number): Pages that failed
- `is_finished` (true/false): True once the crawl is no longer running
- `next_skip` (number): The 'Skip' that gets the next pages, or null when these are the last
- `pages` (list): This batch of pages
- `status` (text): in-progress, completed, failed or cancelled
- `total` (number): Pages found so far

**Example output**

```json
{
  "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 name (`name`, text, required): The profile's name, as 'List profiles' shows it.

**Outputs**

- `cookie_count` (number): Cookies saved in it
- `created_at` (text): When it was created
- `last_used_at` (text): When it was last used, or empty
- `logins` (list): Each saved login and whether it is still valid
- `name` (text): The profile's name, which actions take as 'Sign-in profile'
- `origin_count` (number): Sites whose local storage or IndexedDB it holds
- `profile_id` (text): The profile's ID
- `updated_at` (text): When it last changed

**Example output**

```json
{
  "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**

- Status (`status`, text): 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 page (`limit`, number): Optional. How many to return, from 1 to 100. Browserless returns 20. From 1 to 100.
- Next page cursor (`cursor`, text): Optional. The next_cursor from an earlier call, to get the next page.

**Outputs**

- `next_cursor` (text): Cursor for the next page, or empty when none
- `runs` (list): The runs on this page

**Example output**

```json
{
  "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**

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

**Outputs**

- `crawls` (list): The crawls on this page
- `next_cursor` (text): Cursor for the next page, or empty when none

**Example output**

```json
{
  "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_version` (text): Version of Browserless's scraper catalog
- `scrapers` (list): One row per scraper call

**Example output**

```json
{
  "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 most (`limit`, number): Optional. How many to return, up to 1000. Browserless returns 100. From 1 to 1000.
- Skip (`offset`, number): Optional. How many to skip, to page through them. At least 0.

**Outputs**

- `profile_count` (number): How many came back
- `profiles` (list): The saved profiles

**Example output**

```json
{
  "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 URL (`url`, text, required): The site to start from, starting with http:// or https://.
- Most relevant to (`search`, text): Optional. Order the pages by how well they match this, such as pricing.
- At most (`limit`, number): Optional. The most pages to return, up to 5000. From 1 to 5000.
- Sitemap (`sitemap`, text): 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 subdomains (`include_subdomains`, true/false): Include pages on subdomains, such as blog.example.com. Default: `true`.
- Treat ?query variants as one page (`ignore_query_parameters`, true/false): Drop the ?query part of addresses, so variants count once. Default: `true`.
- Browse from (`country`, text): Optional. Two-letter code of the country to look from, such as GB, for sites that differ by location.
- Proxy network (`proxy`, text): 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_seconds`, number): 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_count` (number): How many pages
- `links` (list): The pages found
- `url` (text): The site mapped

**Example output**

```json
{
  "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**

- Query (`query`, text, required): The BrowserQL (GraphQL) query to run.
- Variables (`variables`, object): Optional. Values for the query's $variables.
- Operation name (`operation_name`, text): Optional. Which named operation to run, when the query has several.
- Stealth mode (`stealth`, true/false): Run on Browserless's stealth browser, which hides that it is automated. Best for bot-protected sites. Default: `false`.
- Proxy network (`proxy`, text): 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 country (`proxy_country`, text): 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 person (`humanlike`, true/false): Add human-like mouse movement and typing delays. Default: `false`.
- Hide cookie banners (`block_consent_modals`, true/false): Close cookie-consent banners and pop-ups before the capture. Default: `false`.
- Block ads (`block_ads`, true/false): Load the page with an ad blocker, so ads and trackers don't load. Default: `false`.
- Sign-in profile (`profile`, text): 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_seconds`, number): 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**

- `data` (object): What each mutation returned, by its name or alias
- `errors` (list): Errors from mutations that failed, if any

**Example output**

```json
{
  "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 URL (`url`, text, required): The page to load, starting with http:// or https://.
- Categories (`categories`, list): Optional. Which scores to work out. All four if none. One or more of: `performance`, `accessibility`, `best-practices` (Best practices), `seo`.
- Only these audits (`audits`, list): 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_seconds`, number): 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_score` (number): Out of 100, or null if not audited
- `best_practices_score` (number): Out of 100, or null if not audited
- `failed_audits` (list): Audits scoring under 90, worst first
- `fetched_at` (text): When the audit ran (ISO 8601)
- `final_url` (text): Where the page ended up after redirects
- `lighthouse_version` (text): The Lighthouse version that ran
- `metrics` (list): The speed metrics, when performance was audited
- `performance_score` (number): Out of 100, or null if not audited
- `seo_score` (number): Out of 100, or null if not audited
- `url` (text): The page audited
- `warnings` (list): Problems Lighthouse ran into while auditing

**Example output**

```json
{
  "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**

- Scraper (`scraper`, text, required): The scraper, as 'List predefined scrapers' names it.
- Call (`api`, text, required): Which of its calls to make, such as search or property.
- Inputs (`scraper_params`, object): 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 URL (`url`, text): Optional. A page on the site instead of inputs, such as a Zillow listing for the property call.
- Give up after (seconds) (`timeout_seconds`, number): 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**

- `api` (text): The call made
- `data` (object): What it found, in the shape 'List predefined scrapers' describes
- `scraper` (text): The scraper

**Example output**

```json
{
  "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**

- Code (`code`, text, required): 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.
- Context (`context`, object): Optional. Values to hand the code as context, such as a URL or a search term from an earlier step.
- Stealth mode (`stealth`, true/false): Hide the signs of an automated browser from bot detection. Turn on for sites that block or challenge headless browsers. Default: `false`.
- Proxy network (`proxy`, text): 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 country (`proxy_country`, text): 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 ads (`block_ads`, true/false): Load the page with an ad blocker, so ads and trackers don't load. Default: `false`.
- Sign-in profile (`profile`, text): 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_seconds`, number): 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_size` (number): Size of the file the code returned, if any, in bytes
- `content_type` (text): MIME type of the file the code returned, if any,
- `document_ref` (text): ID of the stored file the code returned, if any,, for a later step that takes a file
- `documents` (list): The file the code returned, if any,, saved to your workspace's file storage
- `filename` (text): 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
- `url` (text): Link that serves the file the code returned, if any,

**Example output**

```json
{
  "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 URL (`url`, text, required): The page to load, starting with http:// or https://.
- Proxy network (`proxy`, text): 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 country (`proxy_country`, text): 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_seconds`, number): 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 first (`browser_actions`, list): 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 profile (`profile`, text): 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_size` (number): Size of the PDF in bytes
- `content_type` (text): MIME type of the PDF
- `document_ref` (text): ID of the stored PDF, for a later step that takes a file
- `documents` (list): The PDF, saved to your workspace's file storage
- `filename` (text): Name the PDF was stored under
- `page_url` (text): The page that was captured
- `status_code` (number): HTTP status the page responded with
- `strategy` (text): How Browserless fetched the page: http-fetch, http-proxy, browser or browser-captcha
- `title` (text): The page's title
- `url` (text): Link that serves the PDF

**Example output**

```json
{
  "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 URL (`url`, text, required): The page to load, starting with http:// or https://.
- Proxy network (`proxy`, text): 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 country (`proxy_country`, text): 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 footers (`only_main_content`, true/false): Leave out navigation, footers, sidebars, scripts and styles. Can't be combined with 'Only these parts'. Default: `false`.
- Only these parts (`include_tags`, list): 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 parts (`exclude_tags`, list): 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_seconds`, number): 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 headers (`headers`, object): Optional. Extra HTTP headers to send to the site, such as Accept-Language. Browserless drops cookie, authorization and forwarding headers.
- Do first (`browser_actions`, list): 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 profile (`profile`, text): 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**

- `attempted` (list): Every strategy tried, in order
- `content` (text): The page's HTML. If the URL answers with JSON instead, this is that JSON as a string; for a PDF, its text.
- `content_type` (text): Content type the page was served with
- `description` (text): The page's meta description
- `language` (text): The page's language, such as en
- `markdown` (text): The page as markdown, with scripts, styles, and hidden elements stripped
- `raw_text` (text): The page's text, whitespace collapsed
- `response_headers` (object): HTTP headers the site answered with
- `script_results` (list): What each 'executeJavascript' browser action returned
- `snapshots` (list): What each 'scrape' browser action saw
- `status_code` (number): HTTP status the page responded with
- `strategy` (text): How Browserless fetched the page: http-fetch, http-proxy, browser or browser-captcha
- `title` (text): The page's title
- `url` (text): The page that was scraped

**Example output**

```json
{
  "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 URL (`url`, text): The page to load, starting with http:// or https://. Leave empty to render the HTML instead.
- CSS selectors (`selectors`, list, required): One or more CSS selectors, such as h1, .price or table tr td:first-child. Every match of each comes back.
- HTML (`html`, text): HTML to render instead of loading a page, with any CSS in <style> tags. Fill in either this or the page URL.
- Wait for element (`wait_for_selector`, text): 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_seconds`, number): Optional. Seconds to let the page fill itself in after it loads, up to 30. From 0 to 30.
- Page counts as loaded when (`wait_until`, text): 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 out (`best_attempt`, true/false): Use the page as it is when a wait or the navigation times out, instead of failing the step. Default: `false`.
- Don't load (`block_resources`, list): 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 headers (`headers`, object): Optional. Extra HTTP headers to send with every request the page makes, such as Accept-Language.
- Stealth mode (`stealth`, true/false): Hide the signs of an automated browser from bot detection. Turn on for sites that block or challenge headless browsers. Default: `false`.
- Proxy network (`proxy`, text): 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 country (`proxy_country`, text): 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 ads (`block_ads`, true/false): Load the page with an ad blocker, so ads and trackers don't load. Default: `false`.
- Sign-in profile (`profile`, text): 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_seconds`, number): 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**

- `results` (list): One entry per selector, in the order given
- `url` (text): The page that was loaded, or empty for HTML

**Example output**

```json
{
  "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 URL (`url`, text, required): The page to load, starting with http:// or https://.
- Proxy network (`proxy`, text): 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 country (`proxy_country`, text): 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_seconds`, number): 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 first (`browser_actions`, list): 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 profile (`profile`, text): 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_size` (number): Size of the screenshot in bytes
- `content_type` (text): MIME type of the screenshot
- `document_ref` (text): ID of the stored screenshot, for a later step that takes a file
- `documents` (list): The screenshot, saved to your workspace's file storage
- `filename` (text): Name the screenshot was stored under
- `page_url` (text): The page that was captured
- `status_code` (number): HTTP status the page responded with
- `strategy` (text): How Browserless fetched the page: http-fetch, http-proxy, browser or browser-captcha
- `title` (text): The page's title
- `url` (text): Link that serves the screenshot

**Example output**

```json
{
  "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 for (`query`, text, required): What to search for.
- Results (`limit`, number): Optional. Results per source, up to your plan's cap (Free 3, Prototyping 5, Starter 10, Scale 20). From 1 to 20.
- Search in (`sources`, list): Optional. The web unless chosen otherwise. One or more of: `web`, `news`, `images`.
- Language (`lang`, text): Optional. Language code of the results, such as en or de.
- Search from (`country`, text): Optional. Two-letter country code, such as US or GB.
- Search near (`location`, text): Optional. A place for local results, such as San Francisco.
- From the past (`time_range`, text): Optional. Only results from this recent period. One of: `day`, `week`, `month`, `year`.
- Only these kinds of site (`categories`, list): Optional. Narrow web results to these. One or more of: `github` (GitHub repositories), `research` (Research papers), `pdf` (PDF documents).
- Also read each result as (`scrape_formats`, list): 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 article (`only_main_content`, true/false): When reading result pages, keep only each page's main article. Default: `false`.
- Proxy network (`proxy`, text): 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_seconds`, number): 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**

- `images` (list): Image results, when images were searched
- `news` (list): News results, when news was searched
- `query` (text): What was searched for
- `total_results` (number): How many results came back in all
- `web` (list): Web results

**Example output**

```json
{
  "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**

- Task (`task`, text, required): What the agent should do, at least 10 characters, such as 'Find the price of the Pro plan on browserless.io'.
- Start at (`start_url`, text): Optional. The page the agent opens first.
- Only these sites (`allowed_domains`, list): Optional. Domains the agent may visit, such as browserless.io.
- Most browser steps (`max_steps`, number): 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_minutes`, number): Optional. Up to 15, which is the default. From 0.5 to 15.
- Answer shape (`response_schema`, object): Optional. A JSON Schema for the answer, so 'data' comes back in that shape. Best effort, so check the result.
- Capture the last page as (`page_captures`, list): 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 network (`proxy`, text): 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 country (`proxy_country`, text): 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 mode (`stealth`, true/false): Hide the signs of an automated browser from bot detection. Turn on for sites that block or challenge headless browsers. Default: `false`.
- Solve captchas (`solve_captchas`, true/false): Let the agent solve captchas it meets. Default: `false`.
- Sign-in profile (`profile`, text): 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-ins (`pause_for_human`, true/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 replay (`record_replay`, true/false): Record the session for Session Replay in your Browserless dashboard. Default: `false`.
- Webhook URL (`webhook_url`, text): Optional. An https:// address Browserless calls when the job finishes, such as a Lodol webhook trigger.
- Call the webhook when (`webhook_events`, list): 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_id` (text): The run's ID, for 'Get agent run'
- `status` (text): pending

**Example output**

```json
{
  "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 URL (`url`, text): The page to load, starting with http:// or https://. Leave empty to render the HTML instead.
- HTML (`html`, text): HTML to render instead of loading a page, with any CSS in <style> tags. Fill in either this or the page URL.
- Image format (`image_format`, text): Optional. PNG unless chosen otherwise. One of: `png` (PNG: sharp, larger files), `jpeg` (JPEG: smaller files, no transparency), `webp` (WebP: smallest files).
- Quality (`quality`, number): 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 page (`full_page`, true/false): Capture the whole page, scrolled top to bottom. Turn off for just the visible window. Default: `true`.
- Only this element (`selector`, text): Optional. CSS selector of one element to capture, cropped to its edges, such as #chart.
- Window width (px) (`viewport_width`, number): Optional. Browser window width; give the height too. From 1 to 8000.
- Window height (px) (`viewport_height`, number): Optional. Browser window height; give the width too. From 1 to 8000.
- Pixel density (`device_scale_factor`, number): Optional. 2 for a sharp, retina-style image. Needs a window width and height. From 0.1 to 4.
- Transparent background (`omit_background`, true/false): Leave out the page's default white background, for a PNG or WebP with transparency. Default: `false`.
- Scroll through first (`scroll_page`, true/false): Scroll down the page before capturing, so images that load as you scroll are in the shot. Default: `false`.
- Hide cookie banners (`block_consent_modals`, true/false): Close cookie-consent banners and pop-ups before the capture. Default: `false`.
- Wait for element (`wait_for_selector`, text): 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_seconds`, number): Optional. Seconds to let the page fill itself in after it loads, up to 30. From 0 to 30.
- Page counts as loaded when (`wait_until`, text): 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 out (`best_attempt`, true/false): Use the page as it is when a wait or the navigation times out, instead of failing the step. Default: `false`.
- Stealth mode (`stealth`, true/false): Hide the signs of an automated browser from bot detection. Turn on for sites that block or challenge headless browsers. Default: `false`.
- Proxy network (`proxy`, text): 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 country (`proxy_country`, text): 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 ads (`block_ads`, true/false): Load the page with an ad blocker, so ads and trackers don't load. Default: `false`.
- Sign-in profile (`profile`, text): 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_seconds`, number): 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 name (`filename`, text): Optional. Name to store the file under. Leave empty to name it after the page.

**Outputs**

- `byte_size` (number): Size of the screenshot in bytes
- `content_type` (text): MIME type of the screenshot
- `document_ref` (text): ID of the stored screenshot, for a later step that takes a file
- `documents` (list): The screenshot, saved to your workspace's file storage
- `filename` (text): Name the screenshot was stored under
- `final_url` (text): Where the page ended up after any redirects
- `page_url` (text): The page that was loaded, or empty for rendered HTML
- `status_code` (number): HTTP status the site answered with, or 0 for rendered HTML
- `url` (text): Link that serves the screenshot

**Example output**

```json
{
  "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 URL (`url`, text, required): The page to load, starting with http:// or https://.
- Return the HTML (`return_html`, true/false): Return the page's HTML once it is unblocked. Default: `true`.
- Return the cookies (`return_cookies`, true/false): Return the cookies the site set. Default: `true`.
- Take a screenshot (`return_screenshot`, true/false): Also save a full-page JPEG of the unblocked page. Default: `false`.
- Proxy network (`proxy`, text): 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 country (`proxy_country`, text): 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 captchas (`solve_captchas`, true/false): Solve a captcha that stands in the way. Each solve spends extra units. Default: `false`.
- Wait for element (`wait_for_selector`, text): 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_seconds`, number): Optional. Seconds to let the page fill itself in after it loads, up to 30. From 0 to 30.
- Page counts as loaded when (`wait_until`, text): 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 out (`best_attempt`, true/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_seconds`, number): 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_solved` (true/false): True when Browserless found a bot challenge and solved it
- `cookies` (list): The cookies the site set, if asked for
- `document_ref` (text): ID of the stored screenshot, or empty when there is none
- `documents` (list): The screenshot, saved to your workspace's file storage. Empty when none was taken.
- `html` (text): The page's HTML, or empty if not asked for
- `screenshot_url` (text): Link that serves the screenshot, or empty
- `url` (text): The page that was unblocked

**Example output**

```json
{
  "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/"
}
```