Browserless

Export a webpage from a URL via the Browserless /export API. Fetches the URL and returns its content in the native format (HTML, PDF, image, etc.). Automatically detects the content type. Set includeResources=true to bundle all page assets (CSS, JS, images) into a ZIP archive for offline use.

Load a Browserless agent skill on demand, or discover site-specific recipes. Two uses: - **{ site: "<host>" }** — list any **site-specific recipes** tuned for that host (e.g. `{ site: "ebay.com" }`), returned as pointers. Do this as soon as you know the host you're about to drive; if one matches your task, load it by id. Returns a "no recipe" note when there's none. - **{ id: "<id>" }** — load a skill body: an in-house skill id (list below) OR a site recipe id `host/slug` from a `site` lookup. Use the in-house skills below when you suspect the page exhibits a non-trivial mechanic but no SKILL block was auto-injected. The auto-injection heuristics are conservative; calling this tool is the explicit fallback. Available in-house skills: - **shadow-dom** — deep selectors, iframe URL-pattern syntax, what works through deep-ref - **cookie-consent** — vendor-specific dismiss recipes (OneTrust, Cookiebot, Didomi, etc.) - **modals** — close-button heuristics, ESC handling, alertdialog vs. dialog - **snapshot-misses** — truncated/empty snapshots, image-rendered content - **dynamic-content** — choosing the right `wait*` method after async triggers - **screenshots** — when to screenshot vs. snapshot, scope and format choices - **tabs** — multi-tab workflows, peek-without-switching - **autonomous-login** — load before authenticating: when the user asked you to log in, when a wall blocks the task, or as soon as a password input appears. Covers the don't-login-by-default posture, contextual credential matching, MFA/captcha branches, and the required final JSON response shape. - **captchas** — the `solve` command, response semantics, escalation path (Cloud-only) - **file-transfers** — `uploadFile` / `getDownloads`, stdio-path vs. base64 content, size caps

READ CAREFULLY: Execute browser commands in persistent agent session. ## Core Loop (ReAct: Reason → Act → Observe) 0. **Plan + check for a site recipe** — restate the goal, decide the target host, then `browserless_skill { site: "<host>" }` (see above). Load and follow any matching recipe before writing your own plan. Never jump straight to `goto`. 1. **goto** — waits "domcontentloaded" 2. **snapshot** — returns interactive + informational elements (button, link, textbox, combobox, checkbox, heading, img+alt) with ref= selectors 3. **Plan** all actions from snapshot 4. **Batch** execute 5. **Re-snapshot** only if page changed 6. Repeat → **close** when done ## Ending the session (REQUIRED) An open session holds one of the account's concurrent browsers until it idles out — leaving it open is not free, and stacking them starves the next task. - **Task complete? Close it.** Send `{ "method": "close" }` as its own call, as the last thing you do. This is the default for one-shot work (a lookup, a scrape, a form submit): close without asking. - **Ask instead of guessing** only when follow-up in the SAME browser is genuinely likely (the user said "then...", you're mid-flow on a logged-in site, or the result invites a next step). Say the browser is still open, ask whether to close it, and close it as soon as they're done. - **Never** end your reply with a live session and no mention of it. Either it's closed, or you told the user it's open and why. ## Site recipes (site-specific, NOT auto-injected) — CHECK FIRST Many specific sites (marketplaces, gov portals, travel, real-estate, etc.) have a **tuned recipe** for a given task — proven selectors, API shortcuts, proxy needs, and known gotchas that a from-scratch plan will miss. These are **not** auto-injected; you must ask for them, and a recipe **overrides** any plan you'd build yourself (including "just use a prefiltered URL + evaluate"). **This is step 0 of every task — do it before your first `goto`.** The moment you know the target host (the user named the site, or you resolved which site to use), call `browserless_skill { site: "<host>" }` — e.g. `{ site: "airbnb.com" }`. If it lists a recipe matching your task, load it with `browserless_skill { id: "<host>/<slug>" }` and follow it. Only when there's no match do you plan the steps yourself. Skipping this check on a supported site is a mistake — it's one cheap call. **Report the outcome (only if you loaded a site recipe).** As your final command in the run, send `{ method: "reportSkillOutcome", params: { domain: "<host>", task: "<slug>", success: <bool> } }` inside `commands` — where `domain`/`task` are the loaded recipe's `<host>`/`<slug>` and `success` is whether the recipe actually got you the result. This refines shared recipes and retires ones that stop working. Send it once, and only when you loaded a recipe — never for a self-planned run. Send it as your last command **before** any `close` (close ends the run and anything after it is dropped). ## Proxy (optional) Proxy config is a **top-level tool argument** (`proxy`, `proxyCountry`, etc. on the tool call itself) — it is applied when the session is opened. **NEVER call `proxy` as a method inside `commands`** — a `{ method: "proxy", ... }` JSON-RPC mutation does NOT change the upstream proxy on an already-open session and will silently no-op. **If there is credible evidence the task needs a proxy, you MUST pass proxy options on the very FIRST call** (before any `goto`/`snapshot`), because the config is read once at session creation. Credible signals include: the user asks for a specific country/region/locale; the target site is known to geo-restrict or block datacenter IPs (streaming, ticketing, retail, banking, real-estate, news paywalls); a prior attempt returned 403/451/captcha/"unusual traffic"/"access denied"; the user explicitly mentions residential / sticky IP / proxy. If you already opened a session without a proxy and now realize one is needed, you must `close`…

Search the web using Browserless and optionally scrape each result. Performs web searches via SearXNG and can return results from web, news, or images. Optionally scrape each result URL to get markdown, HTML, links, or screenshots. Useful for research, gathering information, and finding relevant web pages.

Run a Lighthouse performance audit on any URL via the Browserless /performance API. Returns scores and metrics for accessibility, best practices, performance, PWA, and SEO. Optionally filter by category or supply performance budgets. Note: audits can take 30s–120s depending on the site.

Read the Browserless account behind the current API token: plan, unit balance, billing period, and the names of the account API keys. Use it to answer "what plan am I on", "how many units are left", or "which keys exist". Read-only, and never returns API token values.

Read request and unit consumption for the Browserless account behind the current API token: successes, errors, timeouts, queueing, peak concurrency, captchas, proxy bytes and units. Use it to answer "how much have I used" or "why is my bill high". For per-request detail on failures, use browserless_logs instead. Read-only.

Inspect the sessions on the Browserless account behind the current API token: browsers running right now, persistent sessions saved on dedicated workers, recorded session replays, and 1Password credential integrations. Use it to answer "what is running", "did my session survive", or "what got recorded". Read-only — it never stops a session. Action `replay` downloads one recording and returns a fully self-contained playable rrweb page, needing no network to render: display it inline if you can render HTML, otherwise build an artifact from the returned instructions so the user can watch it. Always show the replay — never just summarise it in words.

Read Browserless's own record of the account's recent requests: what was attempted, whether it failed, why it stopped, how long it took and what it cost. This is the tool for diagnosing a run that failed on the Browserless side rather than in your own code. The window available depends on the account plan; the server reports the limit if a range is refused. Read-only.

Scrape a SINGLE webpage and return its content as markdown or HTML. Handles JavaScript-heavy pages and anti-bot measures automatically. For content across MULTIPLE pages of a site, use browserless_crawl; to list a site's URLs, use browserless_map.

Execute custom Puppeteer JavaScript code on the Browserless cloud. Your function receives a Puppeteer `page` object and optional `context` data. Return { data, type } to control the response payload and Content-Type. For binary outputs, set `type` to a real MIME so the bytes come back as a proper content block instead of base64 text: - `image/png` / `image/jpeg` / `image/webp` → vision content block (~1.5K tokens) - `audio/mpeg` / `audio/wav` → audio content block - `application/pdf` and other binaries → resource content block (attachment) Text responses are capped at 200,000 characters (~50K tokens). Larger text payloads will be rejected — filter or summarize inside your function, or switch to a binary type if you actually meant to return bytes. Useful for complex scraping, form filling, or any browser automation that requires custom code.

Discover and map all URLs on a website using Browserless. Scans a site via sitemaps and link extraction to find all pages. Returns a list of URLs with optional titles and descriptions. Use the search parameter to order results by relevance to a query. Useful for site audits, content discovery, and building site maps.

Crawl a website and scrape every discovered page using Browserless. Starts from a seed URL and follows links up to a configurable depth. Supports sitemap discovery, path filtering, subdomain handling, and custom scrape options. Returns scraped content (markdown/HTML) for each page along with metadata. Useful for comprehensive site analysis, content extraction, and data gathering.

List the authentication profiles saved for the current token. A profile is a saved logged-in browser state (cookies + storage) that can be replayed by passing its name as `profile` to other tools. Call this before a task that needs the browser to start signed in, to discover which profiles already exist and pick one by name. Returns each profile name plus cookie/origin counts and last-used time.