For AI agents: a documentation index is available at /llms.txt
Skip to main content

Page

Extends

  • PageGenerated

Accessors

closed

Get Signature

get closed(): boolean;
Returns

boolean

Constructors

Constructor

new Page(transport): Page;

Parameters

ParameterType
transportTransport

Returns

Page

Overrides

PageGenerated.constructor

Methods

$()

$(selector, options?): Promise<ElementHandle | null>;

Passes through certain properties of the browsers' own document.querySelector API

Parameters

ParameterTypeDescription
selectorstring-
options?QuerySelectorOptions-

Returns

Promise<ElementHandle | null>

Inherited from

PageGenerated.$

$$()

$$(selector, options?): Promise<ElementHandle[]>;

Passes through certain properties of the browsers' own document.querySelectorAll API

Parameters

ParameterTypeDescription
selectorstring-
options?QuerySelectorOptions-

Returns

Promise<ElementHandle[]>

Inherited from

PageGenerated.$$

$$eval()

$$eval(selector, options?): Promise<MapSelectorResponse[]>;

Specify a selector that returns multiple nodes in a document (similar to document.querySelectorAll), or JavaScript that returns a NodeList, and this API will respond with details about those DOM nodes. Similar to how "map" works in most functional programming languages and libraries. Useful for mapping over repetitive data in sites and pages like product listings or search results. This will automatically wait for the selector to be present on the page, and is configurable with the "wait" and "timeout" options.

For getting arbitrary DOM attributes back you can specify them via the attribute(name: "data-custom-attribute") property. This will return an object with name and value properties.

You may also continuously map further nested items as well, for instance this query might get all books on a page, and then a nested mapSelector call might list all sellers of that book, or shipping speeds. Hierarchy of data is preserved to pass through the hierarchical data modeled inside the DOM.

This API will always return a list of results back regardless if one or more items are found, or null if none are found.

Using aliases can also give the returned JSON more meaning and better model the data returned by this powerful API.

Browser Automation Protocol divergence: unlike puppeteer's $$eval(selector, pageFunction), this delegates to mapSelector and returns structured MapSelectorResponse[], not a page-function result.

Parameters

ParameterTypeDescription
selectorstringA document.querySelectorAll compatible string, or JavaScript that returns a DOM NodeList. Examples include:
options?MapSelectorOptions-

Returns

Promise<MapSelectorResponse[]>

Inherited from

PageGenerated.$$eval

$eval()

$eval(selector): Promise<string>;

Returns the text content on the given page or by selector when specified

Browser Automation Protocol divergence: unlike puppeteer's $eval(selector, pageFunction), this returns the matched element's text content and takes no page-function argument.

Parameters

ParameterTypeDescription
selectorstringThe DOM selector of the given element you want to return the text of

Returns

Promise<string>

Inherited from

PageGenerated.$eval

addScriptTag()

addScriptTag(options?): Promise<AddScriptTagResponse>;

Reads Puppeteer's client-only path option before sending the BrowserQL mutation. Exactly one content source is required.

Parameters

ParameterType
options?AddScriptTagOptions

Returns

Promise<AddScriptTagResponse>


addStyleTag()

addStyleTag(options?): Promise<AddStyleTagResponse>;

Reads Puppeteer's client-only path option before sending the BrowserQL mutation. Exactly one content source is required.

Parameters

ParameterType
options?AddStyleTagOptions

Returns

Promise<AddStyleTagResponse>


authenticate()

authenticate(
username,
password,
options?): Promise<HTTPResponse | null>;

Provides credentials for HTTP authentication (RFC 7235). When set, any HTTP authentication challenge (401/407) will be answered with the supplied credentials automatically. If an origin is provided, only challenges whose origin matches will use these credentials; otherwise every challenge is answered (Puppeteer-style).

Parameters

ParameterTypeDescription
usernamestringThe username to authenticate with
passwordstringThe password to authenticate with
options?AuthenticateOptions-

Returns

Promise<HTTPResponse | null>

Inherited from

PageGenerated.authenticate

check()

check(selector, options?): Promise<ClickResponse>;

Sets or un-sets the value of a checkbox on the page

Parameters

ParameterTypeDescription
selectorstringThe CSS selector of the element on the page you want to check/uncheck
options?CheckboxOptions-

Returns

Promise<ClickResponse>

Inherited from

PageGenerated.check

click()

click(selector, options?): Promise<ClickResponse>;

Waits for the element to be visible, scrolls to it, then clicks on it with native events

Parameters

ParameterTypeDescription
selectorstringA query-selector compatible string, JavaScript that returns an HTML Node, OR a Browserless-deep query. Examples include:
options?ClickOptions-

Returns

Promise<ClickResponse>

Inherited from

PageGenerated.click

close()

close(): Promise<void>;

Returns

Promise<void>


content()

content(): Promise<string>;

Returns the HTML content of the page or selector when specified. This API can also "clean" HTML markup returned by specifying a "clean" argument with numerous options. Features of the "clean" argument include removal of non-text nodes, removal of DOM attributes, as well as removal of excessive whitespace and newlines. Using "clean" can save nearly 1,000 times the payload size. Useful for LLM's and other scenarios

Returns

Promise<string>

Inherited from

PageGenerated.content

cookies()

cookies(): Promise<StandardCookie[]>;

Sets and gets cookies on the page

Returns

Promise<StandardCookie[]>

Inherited from

PageGenerated.cookies

emit()

emit<K>(event, payload): boolean;

Emit an event to its listeners (primarily internal).

Type Parameters

Type Parameter
K extends "error" | "message" | keyof PageEventMap

Parameters

ParameterType
eventK
payloadPageEvents[K]

Returns

boolean


emulateMediaType()

emulateMediaType(type): Promise<EmulateMediaTypeResponse>;

Emulates the given CSS media type for the page, mirroring the behavior of printing ("print") or on-screen rendering ("screen"). Useful before a pdf or screenshot to control how the page renders.

Parameters

ParameterTypeDescription
typeMediaTypeThe CSS media type to emulate

Returns

Promise<EmulateMediaTypeResponse>

Inherited from

PageGenerated.emulateMediaType

evaluate()

evaluate(content, options?): Promise<string | null>;

Serializes a function argument and unwraps the scalar result value.

Parameters

ParameterType
contentstring | ((...args) => unknown)
options?EvaluateOptions

Returns

Promise<string | null>


fulfill()

fulfill(options?): Promise<FulfillResponse>;

Fulfills matching requests with a canned response instead of letting them hit the network, mirroring the request-interceptor mocking used by the REST APIs. Matching follows the same glob-style URL/method/type conditions as reject.

Parameters

ParameterType
options?FulfillOptions

Returns

Promise<FulfillResponse>

Inherited from

PageGenerated.fulfill

goBack()

goBack(options?): Promise<HTTPResponse | null>;

Goes back in browser history, optionally accepting waitUntil and timeout arguments. Returns null if no back is possible

Parameters

ParameterType
options?NavigationOptions

Returns

Promise<HTTPResponse | null>

Inherited from

PageGenerated.goBack

goForward()

goForward(options?): Promise<HTTPResponse | null>;

Goes forward in browser history, optionally accepting waitUntil and timeout arguments. Returns null if no forward is possible

Parameters

ParameterType
options?NavigationOptions

Returns

Promise<HTTPResponse | null>

Inherited from

PageGenerated.goForward

goto()

goto(url, options?): Promise<HTTPResponse | null>;

Opt-in remote response metadata keeps new clients compatible with older BQL schemas.

Parameters

ParameterType
urlstring
options?GotoOptions

Returns

Promise<HTTPResponse | null>

Overrides

PageGenerated.goto

hover()

hover(selector, options?): Promise<HoverResponse>;

Waits for the element to be visible, scrolls to it, then hover on it with native events

Parameters

ParameterTypeDescription
selectorstringThe CSS selector of the element on the page you want to hover on
options?HoverOptions-

Returns

Promise<HoverResponse>

Inherited from

PageGenerated.hover

html()

html(options?): Promise<HTMLResponse>;

Returns the HTML content of the page or selector when specified. This API can also "clean" HTML markup returned by specifying a "clean" argument with numerous options. Features of the "clean" argument include removal of non-text nodes, removal of DOM attributes, as well as removal of excessive whitespace and newlines. Using "clean" can save nearly 1,000 times the payload size. Useful for LLM's and other scenarios

Parameters

ParameterType
options?HTMLOptions

Returns

Promise<HTMLResponse>

Inherited from

PageGenerated.html

liveURL()

liveURL(options?): Promise<LiveURLResponse>;

Returns a fully-qualified, user-shareable live-URL for streaming the web-browser to an end-user, optionally interactive.

Set 30 second timer for interaction

Parameters

ParameterType
options?LiveURLOptions

Returns

Promise<LiveURLResponse>

Inherited from

PageGenerated.liveURL

loadSecret()

loadSecret(ref, options?): Promise<LoadSecretResponse>;

Fills a credential resolved just-in-time from a configured 1Password integration into a target input. The resolved value never appears in your query or in the response. The session must be started with an integration (the integrationId connection parameter or session field), and the page's origin must be in the integration's allowed-domain list. Once any secret has been filled, capture and page-content readback are disabled for the rest of the session — screenshots, PDFs, screencasts, Live URLs, session recording, and the content-return mutations (evaluate, html, text, querySelector, querySelectorAll, cookies).

Parameters

ParameterTypeDescription
refstringThe 1Password op:// reference (e.g. op://Vault/Item/password), or an alias
options?Omit<LoadSecretOptions, "ref">-

Returns

Promise<LoadSecretResponse>

Inherited from

PageGenerated.loadSecret

mapSelector()

mapSelector(selector, options?): Promise<MapSelectorResponse[]>;

Specify a selector that returns multiple nodes in a document (similar to document.querySelectorAll), or JavaScript that returns a NodeList, and this API will respond with details about those DOM nodes. Similar to how "map" works in most functional programming languages and libraries. Useful for mapping over repetitive data in sites and pages like product listings or search results. This will automatically wait for the selector to be present on the page, and is configurable with the "wait" and "timeout" options.

For getting arbitrary DOM attributes back you can specify them via the attribute(name: "data-custom-attribute") property. This will return an object with name and value properties.

You may also continuously map further nested items as well, for instance this query might get all books on a page, and then a nested mapSelector call might list all sellers of that book, or shipping speeds. Hierarchy of data is preserved to pass through the hierarchical data modeled inside the DOM.

This API will always return a list of results back regardless if one or more items are found, or null if none are found.

Using aliases can also give the returned JSON more meaning and better model the data returned by this powerful API.

Parameters

ParameterTypeDescription
selectorstringA document.querySelectorAll compatible string, or JavaScript that returns a DOM NodeList. Examples include:
options?MapSelectorOptions-

Returns

Promise<MapSelectorResponse[]>

Inherited from

PageGenerated.mapSelector

markdown()

markdown(options?): Promise<MarkdownResponse>;

Returns the page's content converted to Markdown. The HTML is fetched from the page (optionally scoped to a selector) and converted server-side, with script/style/noscript/iframe nodes stripped.

Parameters

ParameterType
options?MarkdownOptions

Returns

Promise<MarkdownResponse>

Inherited from

PageGenerated.markdown

off()

off<K>(event, listener): this;

Remove a listener. Removing the last listener for a subscription-backed event closes the underlying stream.

Type Parameters

Type Parameter
K extends "error" | "message" | keyof PageEventMap

Parameters

ParameterType
eventK
listenerListener<PageEvents[K]>

Returns

this


on()

on<K>(event, listener): this;

Register a listener for a page event. Attaching the first listener for a subscription-backed event (console, request, response) lazily opens the underlying stream; see PageEvents.

Type Parameters

Type Parameter
K extends "error" | "message" | keyof PageEventMap

Parameters

ParameterType
eventK
listenerListener<PageEvents[K]>

Returns

this


once()

once<K>(event, listener): this;

Register a one-shot listener, auto-removed after it fires once.

Type Parameters

Type Parameter
K extends "error" | "message" | keyof PageEventMap

Parameters

ParameterType
eventK
listenerListener<PageEvents[K]>

Returns

this


pdf()

pdf(options?): Promise<Uint8Array<ArrayBufferLike>>;

Generates a PDF of the page with the print CSS media type

Parameters

ParameterType
options?PDFOptions

Returns

Promise<Uint8Array<ArrayBufferLike>>

Inherited from

PageGenerated.pdf

preferences()

preferences(options?): Promise<DefaultResponse>;

Sets configuration for the entirety of the session, replacing defaults like the 30 second timeout default

Parameters

ParameterType
options?PreferencesOptions

Returns

Promise<DefaultResponse>

Inherited from

PageGenerated.preferences

proxy()

proxy(options?): Promise<ProxyResponse>;

Proxies requests, by a specified set of conditions, through either the Browserless residential proxy or through an external proxy. Only requests that match these conditions are proxied and the rest are sent from the instance's own IP address.

Use the "server" argument to specify an external proxy for Browserless to use for requests. For requests with authentication, the username and password should be included in the URL using Basic Authentication. See the examples below for more information on how to format those URLs.

Using the browserless proxy for all requests and proxy through Brazil

Parameters

ParameterType
options?ProxyOptions

Returns

Promise<ProxyResponse>

Inherited from

PageGenerated.proxy

reconnect()

reconnect(options?): Promise<ReconnectionResponse>;

Returns a payload with reconnection information in order to reconnect back to the same browser session

Parameters

ParameterType
options?ReconnectOptions

Returns

Promise<ReconnectionResponse>

Inherited from

PageGenerated.reconnect

reject()

reject(options?): Promise<RejectResponse>;

Rejects requests by a specified URL pattern, method, or type and operator. You may supply a single pattern, or a list (array) of them. This mutation, by default, will reject any requests that match any pattern, which we call an "or" operator. To reject requests where conditions must all match, specify an "and" operator in the mutation. Note that this only has an effect when the query is executing, so scripts that return quickly will likely see assets loading in the editor as these rejections only happen when mutations are executing.


Rejecting images or media

Parameters

ParameterType
options?RejectOptions

Returns

Promise<RejectResponse>

Inherited from

PageGenerated.reject

reload()

reload(options?): Promise<HTTPResponse | null>;

Reloads the given page with an optional waitUntil parameter and timeout parameter

Parameters

ParameterType
options?NavigationOptions

Returns

Promise<HTTPResponse | null>

Inherited from

PageGenerated.reload

removeAllListeners()

removeAllListeners<K>(event?): this;

Remove all listeners for an event, or for every event when omitted.

Type Parameters

Type Parameter
K extends "error" | "message" | keyof PageEventMap

Parameters

ParameterType
event?K

Returns

this


request()

request(options?): Promise<RequestResponse[]>;

Returns request information made by the Browser with optional filters via arguments. You may filter the returned results by a glob-like URL-pattern, the method of the request or the type of request. Applying an operator to this will then change the behavior by either "and"ing the filters together or "or"ing them. This API will automatically wait for the request to be made if none is immediately found which you can turn off by disabling the "wait" option.

Getting all "Document" requests

Parameters

ParameterType
options?RequestFilterOptions

Returns

Promise<RequestResponse[]>

Inherited from

PageGenerated.request

response()

response(options?): Promise<ResponseResponse[]>;

Opt-in body-encoding flag keeps new clients compatible with older BQL schemas.

Parameters

ParameterType
options?ResponseFilterOptions

Returns

Promise<ResponseResponse[]>

Overrides

PageGenerated.response

screenshot()

screenshot(options?): Promise<Uint8Array<ArrayBufferLike>>;

Screenshots the page or a specific selector

Parameters

ParameterType
options?ScreenshotOptions

Returns

Promise<Uint8Array<ArrayBufferLike>>

Inherited from

PageGenerated.screenshot

scroll()

scroll(options?): Promise<ScrollResponse>;

Waits for a selector, then scrolls to it on the page or an x,y coordinate in pixels

Parameters

ParameterType
options?ScrollOptions

Returns

Promise<ScrollResponse>

Inherited from

PageGenerated.scroll

select()

select(selector, ...values): Promise<SelectResponse>;

Varargs collapse to a single value or an array (puppeteer select).

Parameters

ParameterType
selectorstring
...valuesstring[]

Returns

Promise<SelectResponse>


send()

send<T>(query, options?): Promise<T>;

Type Parameters

Type ParameterDefault type
Tunknown

Parameters

ParameterType
querystring
options?SendOptions

Returns

Promise<T>


setContent()

setContent(html, options?): Promise<HTTPResponse | null>;

Sets the given HTML content on the page with an optional waitUntil parameter

Parameters

ParameterTypeDescription
htmlstringWhen present, sets the content of page to the value passed, then returns the pages content
options?SetContentOptions-

Returns

Promise<HTTPResponse | null>

Inherited from

PageGenerated.setContent

setCookie()

setCookie(...cookies): Promise<CookieResponse>;

Varargs of cookie inputs.

Parameters

ParameterType
...cookiesCookieInput[]

Returns

Promise<CookieResponse>


setExtraHTTPHeaders()

setExtraHTTPHeaders(headers): Promise<HTTPHeadersResponse>;

Accepts a Record and reshapes it into the GraphQL [HeaderInput].

Parameters

ParameterType
headersRecord<string, string>

Returns

Promise<HTTPHeadersResponse>


setJavaScriptEnabled()

setJavaScriptEnabled(enabled): Promise<JavaScriptResponse>;

Sets and gets JavaScript execution on the page

Note: changing this value won't affect scripts that have already been run. It will take full effect on the next navigation.

Parameters

ParameterTypeDescription
enabledbooleanWhether or not to enable JavaScript on the page

Returns

Promise<JavaScriptResponse>

Inherited from

PageGenerated.setJavaScriptEnabled

setUserAgent()

setUserAgent(userAgent): Promise<UserAgentResponse>;

Sets the User-Agent string for the browser session

Parameters

ParameterTypeDescription
userAgentstringThe User-Agent string to set for the browser session

Returns

Promise<UserAgentResponse>

Inherited from

PageGenerated.setUserAgent

setViewport()

setViewport(options?): Promise<ViewportResponse>;

Sets the viewport dimensions for the browser session

Parameters

ParameterType
options?ViewportOptions

Returns

Promise<ViewportResponse>

Inherited from

PageGenerated.setViewport

solve()

solve(options?): Promise<CaptchaResponse>;

🚨 EXPERIMENTAL 🚨 Solves a captcha or other challenge. Can auto-detect the CAPTCHA type or solve a specific type. Uses the same detection logic as BaaS to automatically identify the CAPTCHA type and routes to the appropriate solver. Optionally accepts a specific type to solve.

Parameters

ParameterType
options?SolveOptions

Returns

Promise<CaptchaResponse>

Inherited from

PageGenerated.solve

solveImageCaptcha()

solveImageCaptcha(options?): Promise<CaptchaResponse>;

Solves an image captcha using caller-provided selectors. Unlike solve, which auto-detects known captcha types, this mutation works on any site by accepting custom captchaSelector and inputSelector arguments. It detects the captcha image, solves it, and fills the result into the specified input field.

Parameters

ParameterType
options?SolveImageCaptchaOptions

Returns

Promise<CaptchaResponse>

Inherited from

PageGenerated.solveImageCaptcha

stopSessionRecording()

stopSessionRecording(): Promise<StopSessionRecordingResponse>;

Stops the current session recording and processes the replay data, similar to closing the context. This mutation will stop RRWeb recording and upload the collected events.

Returns

Promise<StopSessionRecordingResponse>

Inherited from

PageGenerated.stopSessionRecording

subscribe()

subscribe(listener): () => void;

Sugar for Page.on('message', …) that returns an unsubscribe fn.

Parameters

ParameterType
listenerMessageListener

Returns

() => void


switchToWindow()

switchToWindow(options?): Promise<SwitchWindowResponse>;

Switches context to a popup window matching specified criteria

Parameters

ParameterType
options?SwitchToWindowOptions

Returns

Promise<SwitchWindowResponse>

Inherited from

PageGenerated.switchToWindow

text()

text(options?): Promise<TextResponse>;

Returns the text content on the given page or by selector when specified

Parameters

ParameterType
options?TextOptions

Returns

Promise<TextResponse>

Inherited from

PageGenerated.text

title()

title(): Promise<string>;

Returns the title of the page that the browser is currently at

Returns

Promise<string>

Inherited from

PageGenerated.title

type()

type(
selector,
text,
options?): Promise<TypeResponse>;

Types text into an element by scrolling to it, clicking it, then emitting key events for every character. Include a \n (or \r) in text to send an Enter/Return key press — useful for submitting search boxes or forms without a separate click. BrowserQL has no standalone key-press mutation, so non-Enter keys cannot be simulated; use click for non-keyboard submit interactions (for example, a submit button).

Parameters

ParameterTypeDescription
selectorstringThe CSS selector of the element on the page you want to type text into
textstringThe text content you want to type into the element. A \n or \r character is sent as an Enter key press.
options?TypeOptions-

Returns

Promise<TypeResponse>

Inherited from

PageGenerated.type

uncheck()

uncheck(selector, options?): Promise<ClickResponse>;

Sets or un-sets the value of a checkbox on the page

Parameters

ParameterTypeDescription
selectorstringThe CSS selector of the element on the page you want to check/uncheck
options?CheckboxOptions-

Returns

Promise<ClickResponse>

Inherited from

PageGenerated.uncheck

url()

url(): Promise<string>;

Returns the URL of the page that the browser is currently at

Returns

Promise<string>

Inherited from

PageGenerated.url

waitForEvent()

waitForEvent(event, options?): Promise<WaitForEvent>;

Leaves enough transport time for BrowserQL to return its own timeout result instead of racing the client timer at the same millisecond.

Parameters

ParameterType
eventstring
options?WaitForEventOptions

Returns

Promise<WaitForEvent>

Overrides

PageGenerated.waitForEvent

waitForFunction()

waitForFunction(fn, options?): Promise<WaitForFunction>;

Preserves the REST compatibility mode that considers an async function complete once its returned promise settles, without changing the default BrowserQL predicate semantics for other callers.

Parameters

ParameterType
fnstring
options?WaitForFunctionOptions

Returns

Promise<WaitForFunction>


waitForNavigation()

waitForNavigation(options?): Promise<HTTPResponse>;

Waits for a navigation even to fire, useful for clicking an element and waiting for a page load of some

Parameters

ParameterType
options?WaitForNavigationOptions

Returns

Promise<HTTPResponse>

Inherited from

PageGenerated.waitForNavigation

waitForNetworkIdle()

waitForNetworkIdle(options?): Promise<WaitForTimeoutResponse>;

Wait for the page to have no more than the configured number of in-flight network requests for a period of time.

Parameters

ParameterType
options?WaitForNetworkIdleOptions

Returns

Promise<WaitForTimeoutResponse>

Inherited from

PageGenerated.waitForNetworkIdle

waitForRequest()

waitForRequest(urlOrOptions?): Promise<WaitForRequestResponse>;

Accepts a bare URL string or an options object.

Parameters

ParameterType
urlOrOptions?| string | WaitForRequestOptions

Returns

Promise<WaitForRequestResponse>


waitForResponse()

waitForResponse(urlOrOptions?): Promise<WaitForResponseResponse>;

Accepts a bare URL string or an options object.

Parameters

ParameterType
urlOrOptions?| string | WaitForResponseOptions

Returns

Promise<WaitForResponseResponse>


waitForSelector()

waitForSelector(selector, options?): Promise<WaitForSelectorResponse>;

Waits for a given selector to be present in the DOM, with optional visibility

Parameters

ParameterTypeDescription
selectorstringThe selector to wait for until present in the DOM
options?WaitForSelectorOptions-

Returns

Promise<WaitForSelectorResponse>

Inherited from

PageGenerated.waitForSelector

waitForTimeout()

waitForTimeout(ms): Promise<void>;

Milliseconds → the GraphQL time arg, with a transport timeout cushion.

Parameters

ParameterType
msnumber

Returns

Promise<void>


watchEvent()

watchEvent(event): Promise<WaitForEvent>;

Starts tracking a named document/window event in the current document and before scripts execute in future documents. A later waitForEvent call returns immediately when the tracked event has already fired.

Parameters

ParameterTypeDescription
eventstringThe name of the event to track, eg: "load" or a custom event name

Returns

Promise<WaitForEvent>

Inherited from

PageGenerated.watchEvent