Browserless API Endpoints Explained: Which One Should You Use?

Short answer: choose the Browserless endpoint by the result you need: /content for rendered HTML, /scrape for selector-based JSON, /screenshot for an image, and /pdf for a PDF. Use /function when the task needs custom Puppeteer steps. REST requests are one-shot: the browser session closes after the task. For state that must persist between requests, use Browserless BaaS sessions or BrowserQL instead.

This guide explains which endpoint fits each job, how to choose between them, and where a separate screenshot API may be simpler.

1. Which Browserless API should you use?

Your task	Use	Result and fit
Get the JavaScript-rendered page markup	/content	Rendered HTML (text/html) to parse yourself.
Extract known fields with CSS selectors	/scrape	Structured JSON based on requested selectors and properties.
Extract with an automatic HTTP/browser choice	/smart-scrape	JSON; tries HTTP first and falls back to a full browser.
Capture a rendered page as an image	/screenshot	PNG, JPEG, or WebP; supports full-page capture.
Render a document	/pdf	PDF output.
Run custom browser steps or extraction logic	/function	Your Puppeteer code runs in one execution session; the session closes when it finishes.
Find URLs, crawl, retrieve files, or export responses	/search, /map, /crawl, /download, or /export	Use the endpoint whose discovery, crawl, download, or native-type retrieval job matches yours; check its specific inputs and constraints.
Run a Lighthouse audit	/performance	JSON performance metrics.
Attempt to retrieve a protected page	/unblock	Can return selected content, cookies, a screenshot, or a browser WebSocket endpoint. Results depend on the site’s protections.
Keep state across steps or requests	BaaS sessions or BrowserQL	Choose a session-management or persisted-state workflow instead of stateless REST.

These paths are documented in the Browserless REST API overview. Start from the output format, then check whether your job needs interaction or state that spans requests.

2. Understand the REST request lifecycle

A Browserless REST call is designed for one browser task in one HTTP request: it launches a browser, performs the task, returns the response, and closes the session. This works well for independent captures, HTML retrieval, and selector extraction. It is not a sequence of REST calls that implicitly shares one browser with cookies and page state.

If a workflow requires navigating, clicking, filling a form, and then extracting data in one flow, put those steps in one /function execution or use a session-oriented option. /function gives you custom logic for that execution; it does not make the browser persist after the function returns. For longer-lived state, the docs point to BaaS session management or BrowserQL persisted state and reconnect.

3. Choose by output: HTML, JSON, image, or PDF

Rendered HTML: /content

Choose /content when you need the rendered document and want to decide how to parse it. It is the direct fit when the page content is produced by JavaScript and you need the resulting markup, rather than a screenshot or predefined fields.

Structured fields: /scrape or /smart-scrape

Choose /scrape when you know which fields to collect and can describe them with CSS selectors and extraction properties. The response is structured JSON, and the endpoint supports waits for JavaScript or lazy-loaded elements. Choose /smart-scrape when you want its documented automatic fallback approach: it tries HTTP first, then falls back to a full browser. Neither option changes the need to inspect the endpoint’s request schema for exact selector and wait fields.

Image: /screenshot

Choose /screenshot when the desired artifact is a rendered image. It supports PNG, JPEG, and WebP, plus screenshot options such as full-page capture. If the task is simply “URL in, image out,” a screenshot endpoint is more direct than returning HTML and writing your own browser capture code.

Document: /pdf

Choose /pdf when the deliverable is a PDF. Use the endpoint-specific documentation for its available rendering parameters; do not assume that options from /screenshot map one-for-one to PDF settings.

4. When custom logic calls for /function

Use /function when the specialized endpoint does not express the steps you need: for example, custom Puppeteer navigation, interaction, or extraction logic. Browserless runs caller-supplied Puppeteer code in one execution session and lets the function choose the response content type. The execution ends with that task, so use a session workflow if later requests must continue with the same browser state.

For a simple capture, extraction, or PDF, prefer the purpose-built endpoint: its request is easier to keep focused on that output. Move to /function when custom steps are actually required, and consult the official function endpoint documentation for the current code contract and limits.

5. Bot protection and the /unblock decision

/unblock is intended for supported attempts to retrieve protected pages and can return selected content, cookies, a screenshot, or a browser WebSocket endpoint. Treat it as conditional assistance, not guaranteed access: advanced fingerprinting and interactive CAPTCHAs can still prevent a REST request from succeeding. The Browserless overview recommends BrowserQL for advanced cases.

Do not build a critical workflow around the assumption that an endpoint defeats every site’s access controls. Check the returned response and endpoint behavior, handle a failed or blocked retrieval, and use only automation that is permitted for the target site.

6. Complete request examples for a screenshot

The title is about choosing endpoints, so there is no single request body that works for every endpoint: each endpoint has its own inputs and output type. These examples show the common one-shot screenshot choice, /screenshot. Replace the placeholder token with your Browserless token and set the target URL using the format required by the official API reference. The endpoint overview and endpoint pages are the source of truth for required parameters and deployment-specific URL details.

cURL

curl -X POST "https://production-sfo.browserless.io/screenshot?token=YOUR_BROWSERLESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","options":{"type":"png","fullPage":true}}' \
  --output page.png

Python

import requests

endpoint = "https://production-sfo.browserless.io/screenshot"
response = requests.post(
    endpoint,
    params={"token": "YOUR_BROWSERLESS_TOKEN"},
    json={"url": "https://example.com", "options": {"type": "png", "fullPage": True}},
    timeout=90,
)
response.raise_for_status()
with open("page.png", "wb") as image_file:
    image_file.write(response.content)

Node.js

const endpoint = new URL("https://production-sfo.browserless.io/screenshot");
endpoint.searchParams.set("token", "YOUR_BROWSERLESS_TOKEN");

const response = await fetch(endpoint, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    url: "https://example.com",
    options: { type: "png", fullPage: true },
  }),
});

if (!response.ok) {
  throw new Error(`Screenshot request failed: ${response.status} ${await response.text()}`);
}

const image = Buffer.from(await response.arrayBuffer());
await import("node:fs/promises").then(({ writeFile }) => writeFile("page.png", image));

Browserless connection URLs and parameters can vary by product and region. Confirm the correct host, authentication method, request shape, and screenshot option names in the official screenshot reference before deploying. For /content, /scrape, /pdf, and /function, use each endpoint’s reference rather than reusing the screenshot payload.

7. If the task is only a screenshot: an alternative to try first

For a URL-to-image job where you do not need to manage browser setup or write custom browser steps, ScreenshotNeo is the first alternative to try. It is a website screenshot API and MCP server from Yorker Media. It returns a screenshot or PDF from one GET request. Its clean-shot flow accepts cookie and consent banners like a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Only clean shots are billed: bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the page verdict and billing state in headers.

ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. All features are available on every plan. The free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots. Yearly billing gives two months free.

Or skip the browser setup

Make one GET request. This example saves the returned image bytes as WebP; replace the placeholder with your API key. See the ScreenshotNeo API documentation for available parameters and response details.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

• Cookie banners, popups, and chat widgets are removed before the shot.
• Bot checks, blank pages, and failed loads are never billed.
• An MCP server lets AI agents take screenshots.
• 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000.

Sign up for ScreenshotNeo and get 1,000 screenshots free each month, with no card required.

8. Performance, reliability, and cost considerations

Performance

The documentation reviewed does not provide a numeric endpoint performance comparison, so there is no evidence-based universal “fastest endpoint” ranking. Choose the narrowest endpoint that produces the required result. A selector extraction does not need you to retrieve and parse the whole rendered document; a screenshot job does not need a custom Puppeteer function unless it requires custom steps. For /smart-scrape, the documented HTTP-first fallback is intended to choose a lighter or browser-based path, but it is not a published latency guarantee.

Reliability

• Handle unsuccessful HTTP responses and timeouts in your client.
• For JavaScript or lazy content, use the endpoint’s documented wait controls where available, especially for /scrape.
• Keep one-shot jobs independent; do not expect cookies or page state to carry between REST requests.
• For multi-step workflows, put the actions in one function execution or use a persistent session approach.
• For protected pages, plan for access to fail; /unblock is not a guarantee against advanced fingerprinting or interactive challenges.

Cost

The reviewed Browserless endpoint material provides no common per-endpoint price comparison, so check your account and plan terms for current cost and concurrency details. Avoid inferring that one endpoint is cheaper or faster based on its name. For a pure screenshot use case, ScreenshotNeo publishes its plans: 1,000 free shots each month without a card; $5 for 3,000 on Starter, $15 for 15,000 on Growth, $39 for 60,000 on Pro, $99 for 250,000 on Scale, and $249 for 1,000,000 on Business. All listed features are on every plan; annual billing provides two months free.

9. Troubleshooting

Symptom	Likely cause	What to do
Response has the wrong format	You selected an endpoint for a different output: for example, /content returns markup while /screenshot returns image bytes.	Choose the endpoint from the output table; make the client handle the matching content type.
Page content is missing	The content may be rendered after initial navigation or loaded lazily.	Use documented waits for the selector or JavaScript content on /scrape; check the endpoint’s wait behavior and response for your case.
Later request is missing cookies or login state	REST is stateless across responses and closes the browser session.	Perform related actions within a single /function execution or move to BaaS sessions or BrowserQL persisted state.
Custom sequence cannot be expressed	A specialized REST endpoint performs its named task, not an arbitrary chain of browser actions.	Use /function for custom Puppeteer steps, or a persistent session workflow when state must live across calls.
Protected page remains blocked	The site may use advanced fingerprinting or an interactive CAPTCHA.	Do not assume /unblock guarantees access; consider BrowserQL for advanced cases and handle blocked results.
Client saves an unreadable image	An error response may have been saved as if it were an image.	Check the HTTP status before writing bytes, and inspect the response content type and body on errors.
Request times out	Navigation or rendering took longer than the client timeout, or the page did not reach the expected state.	Set a suitable client timeout, use the endpoint’s supported waits, and add bounded retries only for transient failures.

10. A practical endpoint selection checklist

1. Write down the artifact you need: HTML, selected fields, image, PDF, or another file.
2. Pick the matching endpoint from the table.
3. Decide whether the task is one browser action or a sequence of interactions.
4. If multiple requests must share cookies or page state, use a session or persisted-state product.
5. If the site is protected, treat access as uncertain and select a suitable documented path.
6. Check the endpoint’s current reference for its required parameters, authentication, waits, output type, and constraints.
7. Make your client inspect status codes and handle timeouts and non-success responses.

11. FAQ

Can I use /function and keep its browser open afterward?

No. A function runs in one execution session, which closes when it completes. Use BaaS session management or BrowserQL persisted state and reconnect when state must survive.

Which endpoint should I use for JavaScript-rendered HTML?

Use /content when you want the rendered HTML to parse yourself. Use /scrape when you already know the fields and selectors you want returned as JSON.

Does /unblock guarantee access to a CAPTCHA-protected website?

No. The docs describe supported unblock attempts and warn that advanced fingerprinting or interactive CAPTCHAs may still block REST requests.

Is there a documented fastest Browserless REST endpoint?

The reviewed official material contains no named endpoint performance benchmarks. Select by output and workflow requirements, not an unsupported speed ranking.

Which API fits a simple URL-to-screenshot call?

Use Browserless /screenshot if you want its screenshot endpoint. If you want a one-GET screenshot API with consent cleanup and billing only for clean shots, try ScreenshotNeo; its docs describe the available options.