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

Async Page

A BAP page with generated methods and an event lifecycle.

add_cookies​

add_cookies(cookies: Sequence[CookieInput]) -> CookieResponse

add_script_tag​

add_script_tag(*, url: str | UnsetType = UNSET, path: str | Path | UnsetType = UNSET, content: str | UnsetType = UNSET, id: str | UnsetType = UNSET, type: str | UnsetType = UNSET) -> AddScriptTagResponse

add_style_tag​

add_style_tag(*, url: str | UnsetType = UNSET, path: str | Path | UnsetType = UNSET, content: str | UnsetType = UNSET) -> AddStyleTagResponse

authenticate​

authenticate(username: str, password: str, *, origin: str | UnsetType = UNSET) -> HTTPResponse | None

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

check​

check(selector: str, *, scroll: bool | UnsetType = UNSET, timeout: float | UnsetType = UNSET, visible: bool | UnsetType = UNSET, wait: bool | UnsetType = UNSET) -> ClickResponse

Check the checkbox matching selector.

click​

click(selector: str, *, scroll: bool | UnsetType = UNSET, timeout: float | UnsetType = UNSET, visible: bool | UnsetType = UNSET, wait: bool | UnsetType = UNSET) -> ClickResponse

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

close​

close() -> None

close_live_url​

close_live_url(live_url_id: str) -> CloseLiveURLResponse

Closes a Live URL created by this browser session.

closed​

Type: bool

content​

content() -> str

Return the full HTML content of the page as a string.

cookies​

cookies() -> list[StandardCookie]

Return the cookies on the page.

emit​

emit(event: str, payload: object) -> bool

emulate_media​

emulate_media(type: MediaType) -> 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.

eval_on_selector​

eval_on_selector(selector: str) -> str

Return the text content of the first element matching selector. Unlike Playwright's eval_on_selector, this takes no page function: it is a shortcut for text(selector=...).

eval_on_selector_all​

eval_on_selector_all(selector: str, *, timeout: float | UnsetType = UNSET, wait: bool | UnsetType = UNSET) -> list[MapSelectorResponse]

Return details (innerHTML, innerText, id, class) for every element matching selector. Unlike Playwright's eval_on_selector_all, this takes no page function: it is a shortcut for map_selector(selector).

evaluate​

evaluate(expression: str, *, timeout: float | UnsetType = UNSET, url: str | UnsetType = UNSET) -> str | None

fulfill​

fulfill(*, url: list[str] | UnsetType = UNSET, regex: list[str] | UnsetType = UNSET, method: list[Method] | UnsetType = UNSET, type: list[ResourceType] | UnsetType = UNSET, operator: OperatorType | UnsetType = UNSET, status: int | UnsetType = UNSET, content_type: str | UnsetType = UNSET, body: str | UnsetType = UNSET, base64_body: str | UnsetType = UNSET, headers: list[HeaderInput] | UnsetType = UNSET) -> 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.

go_back​

go_back(*, timeout: float | UnsetType = UNSET, wait_until: WaitUntilHistory | UnsetType = UNSET) -> HTTPResponse | None

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

go_forward​

go_forward(*, timeout: float | UnsetType = UNSET, wait_until: WaitUntilHistory | UnsetType = UNSET) -> HTTPResponse | None

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

goto​

goto(url: str, *, timeout: float | UnsetType = UNSET, wait_until: WaitUntilGoto | UnsetType = UNSET, wait_until_all: list[WaitUntilGoto] | UnsetType = UNSET, referer: str | UnsetType = UNSET, referrer_policy: str | UnsetType = UNSET, remote_response_metadata: bool | UnsetType = UNSET) -> HTTPResponse | None

Navigate to a URL with optional waitUntil and timeout parameters.

hover​

hover(selector: str, *, scroll: bool | UnsetType = UNSET, timeout: float | UnsetType = UNSET, visible: bool | UnsetType = UNSET, wait: bool | UnsetType = UNSET, x: float | UnsetType = UNSET, y: float | UnsetType = UNSET) -> HoverResponse

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

html​

html(*, selector: str | UnsetType = UNSET, timeout: float | UnsetType = UNSET, visible: bool | UnsetType = UNSET, clean: CleanInput | UnsetType = UNSET, rewrite: HTMLRewriteInput | UnsetType = UNSET) -> 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

listener_count​

listener_count(event: str) -> int

live_url​

live_url(*, capture_scale: int | UnsetType = UNSET, timeout: float | UnsetType = UNSET, interactable: bool | UnsetType = UNSET, type: LiveURLStreamType | UnsetType = UNSET, quality: int | UnsetType = UNSET, resizable: bool | UnsetType = UNSET, show_browser_interface: bool | UnsetType = UNSET, compressed: bool | UnsetType = UNSET, emulate_components: bool | UnsetType = UNSET, instructions_layout: InstructionsLayout | UnsetType = UNSET, instructions: str | LiveURLInstructions | UnsetType = UNSET, instructions_format: InstructionsFormat | UnsetType = UNSET, instructions_title: str | UnsetType = UNSET, steps: list[str] | UnsetType = UNSET, current_step: int | UnsetType = UNSET, done_label: str | UnsetType = UNSET, fail_label: str | UnsetType = UNSET, requester_name: str | UnsetType = UNSET) -> LiveURLResponse

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

load_secret​

load_secret(ref: str, *, selector: str | UnsetType = UNSET) -> 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).

map_selector​

map_selector(selector: str, *, timeout: float | UnsetType = UNSET, wait: bool | UnsetType = UNSET) -> list[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.

markdown​

markdown(*, selector: str | UnsetType = UNSET, timeout: float | UnsetType = UNSET, visible: bool | UnsetType = UNSET) -> 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.

off​

off(event: EventName, listener: Listener) -> Self

on​

on(event: EventName, listener: Listener) -> Self

once​

once(event: EventName, listener: Listener) -> Self

pdf​

pdf(*, display_header_footer: bool | UnsetType = UNSET, format: PDFPageFormat | UnsetType = UNSET, footer_template: str | UnsetType = UNSET, generate_document_outline: bool | UnsetType = UNSET, generate_tagged_pdf: bool | UnsetType = UNSET, landscape: bool | UnsetType = UNSET, print_background: bool | UnsetType = UNSET, omit_background: bool | UnsetType = UNSET, scale: float | UnsetType = UNSET, timeout: float | UnsetType = UNSET, wait_for_images: bool | UnsetType = UNSET, wait_for_fonts: bool | UnsetType = UNSET, full_page: bool | UnsetType = UNSET, width: float | str | UnsetType = UNSET, header_template: str | UnsetType = UNSET, height: float | str | UnsetType = UNSET, margin_bottom: float | str | UnsetType = UNSET, margin_left: float | str | UnsetType = UNSET, margin_right: float | str | UnsetType = UNSET, margin_top: float | str | UnsetType = UNSET, page_ranges: str | UnsetType = UNSET, prefer_css_page_size: bool | UnsetType = UNSET, transfer_mode: str | UnsetType = UNSET, path: str | UnsetType = UNSET) -> bytes

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

preferences​

preferences(*, timeout: float | UnsetType = UNSET) -> DefaultResponse

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

proxy​

proxy(*, network: ProxyNetwork | UnsetType = UNSET, country: CountryCode | UnsetType = UNSET, city: str | UnsetType = UNSET, state: str | UnsetType = UNSET, sticky: bool | UnsetType = UNSET, preset: str | UnsetType = UNSET, server: str | UnsetType = UNSET, method: list[Method] | UnsetType = UNSET, operator: OperatorType | UnsetType = UNSET, type: list[ResourceType] | UnsetType = UNSET, url: list[str] | UnsetType = UNSET) -> 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.

query_selector​

query_selector(selector: str, *, timeout: float | UnsetType = UNSET, visible: bool | UnsetType = UNSET, html: bool | UnsetType = UNSET) -> ElementHandle | None

Return a handle for the first element matching selector, or None. The element's innerHTML/outerHTML are fetched only with html=True; reading inner_html or outer_html without it raises BAPValueError.

query_selector_all​

query_selector_all(selector: str, *, timeout: float | UnsetType = UNSET, visible: bool | UnsetType = UNSET, html: bool | UnsetType = UNSET) -> list[ElementHandle]

Return handles for every element matching selector. The elements' innerHTML/outerHTML are fetched only with html=True; reading inner_html or outer_html without it raises BAPValueError.

reconnect​

reconnect(*, timeout: float | UnsetType = UNSET) -> ReconnectionResponse

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

reject​

reject(*, enabled: bool | UnsetType = UNSET, method: list[Method] | UnsetType = UNSET, operator: OperatorType | UnsetType = UNSET, type: list[ResourceType] | UnsetType = UNSET, url: list[str] | UnsetType = UNSET, regex: list[str] | UnsetType = UNSET) -> 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

reload​

reload(*, timeout: float | UnsetType = UNSET, wait_until: WaitUntilHistory | UnsetType = UNSET) -> HTTPResponse | None

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

remove_all_listeners​

remove_all_listeners(event: str | None = None) -> Self

request​

request(*, type: list[ResourceType] | UnsetType = UNSET, method: list[Method] | UnsetType = UNSET, timeout: float | UnsetType = UNSET, url: list[str] | UnsetType = UNSET, wait: bool | UnsetType = UNSET, operator: OperatorType | UnsetType = UNSET) -> list[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.

response​

response(*, status: list[int] | UnsetType = UNSET, method: list[Method] | UnsetType = UNSET, operator: OperatorType | UnsetType = UNSET, timeout: float | UnsetType = UNSET, type: list[ResourceType] | UnsetType = UNSET, url: list[str] | UnsetType = UNSET, wait: bool | UnsetType = UNSET, body: bool | UnsetType = UNSET, body_encoding: bool | UnsetType = UNSET) -> list[ResponseResponse]

List responses. Bodies are fetched only with body=True or body_encoding=True; body_encoding=True also adds the base64Encoded flag.

screenshot​

screenshot(*, capture_beyond_viewport: bool | UnsetType = UNSET, clip: ScreenshotClip | UnsetType = UNSET, from_surface: bool | UnsetType = UNSET, full_page: bool | UnsetType = UNSET, omit_background: bool | UnsetType = UNSET, optimize_for_speed: bool | UnsetType = UNSET, quality: float | UnsetType = UNSET, selector: str | UnsetType = UNSET, type: ScreenshotType | UnsetType = UNSET, timeout: float | UnsetType = UNSET, wait_for_images: bool | UnsetType = UNSET, path: str | UnsetType = UNSET) -> bytes

Screenshots the page or a specific selector

scroll​

scroll(*, selector: str | UnsetType = UNSET, through_page: bool | UnsetType = UNSET, timeout: float | UnsetType = UNSET, visible: bool | UnsetType = UNSET, wait: bool | UnsetType = UNSET, x: float | UnsetType = UNSET, y: float | UnsetType = UNSET) -> ScrollResponse

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

select_option​

select_option(selector: str, value: str | Sequence[str]) -> SelectResponse

send​

send(query: str, *, variables: Mapping[str, Any] | None = None, timeout: float | None = None) -> Any

set_content​

set_content(html: str, *, timeout: float | UnsetType = UNSET, wait_until: WaitUntilHistory | UnsetType = UNSET, wait_until_all: list[WaitUntilHistory] | UnsetType = UNSET) -> HTTPResponse | None

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

set_extra_http_headers​

set_extra_http_headers(headers: Mapping[str, str]) -> HTTPHeadersResponse

set_java_script_enabled​

set_java_script_enabled(enabled: bool) -> JavaScriptResponse

Sets and gets JavaScript execution on the page

set_user_agent​

set_user_agent(user_agent: str) -> UserAgentResponse

Sets the User-Agent string for the browser session

set_viewport_size​

set_viewport_size(*, width: float, height: float, device_scale_factor: float | UnsetType = UNSET, mobile: bool | UnsetType = UNSET, has_touch: bool | UnsetType = UNSET, landscape: bool | UnsetType = UNSET) -> ViewportResponse

Sets the viewport dimensions for the browser session

solve​

solve(*, type: CaptchaType | UnsetType = UNSET, timeout: float | UnsetType = UNSET, wait: bool | UnsetType = UNSET) -> 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.

solve_image_captcha​

solve_image_captcha(*, captcha_selector: str, input_selector: str, timeout: float | UnsetType = UNSET) -> 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.

stop_session_recording​

stop_session_recording() -> 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.

subscribe​

subscribe(listener: Listener) -> Callable[[], None]

Listen to every non-handshake raw transport frame.

switch_to_window​

switch_to_window(*, url: str | UnsetType = UNSET, title: str | UnsetType = UNSET, newest: bool | UnsetType = UNSET, timeout: float | UnsetType = UNSET, wait_until: WaitUntilGoto | UnsetType = UNSET) -> SwitchWindowResponse

Switches context to a popup window matching specified criteria

text​

text(*, timeout: float | UnsetType = UNSET, selector: str | UnsetType = UNSET, visible: bool | UnsetType = UNSET, clean: CleanInput | UnsetType = UNSET) -> TextResponse

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

title​

title() -> str

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

type​

type(selector: str, text: str, *, delay: list[int] | UnsetType = UNSET, interactable: bool | UnsetType = UNSET, scroll: bool | UnsetType = UNSET, timeout: float | UnsetType = UNSET, visible: bool | UnsetType = UNSET, wait: bool | UnsetType = UNSET) -> 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).

uncheck​

uncheck(selector: str, *, scroll: bool | UnsetType = UNSET, timeout: float | UnsetType = UNSET, visible: bool | UnsetType = UNSET, wait: bool | UnsetType = UNSET) -> ClickResponse

Uncheck the checkbox matching selector.

url​

url() -> str

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

wait_for_event​

wait_for_event(event: str, *, timeout: float | UnsetType = UNSET) -> WaitForEvent

Wait for the next event payload, bounded by timeout when provided.

wait_for_function​

wait_for_function(expression: str, *, polling: float | UnsetType = UNSET, polling_type: WaitForFunctionPolling | UnsetType = UNSET, timeout: float | UnsetType = UNSET, complete_on_promise_resolution: bool | UnsetType = UNSET) -> WaitForFunction

wait_for_live_complete​

wait_for_live_complete(*, timeout: float | None = None) -> LiveURLCompleteEvent

Wait for the current handoff or next mint.

wait_for_navigation​

wait_for_navigation(*, timeout: float | UnsetType = UNSET, wait_until: WaitUntilGoto | UnsetType = UNSET) -> HTTPResponse

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

wait_for_network_idle​

wait_for_network_idle(*, idle_time: float | UnsetType = UNSET, concurrency: int | UnsetType = UNSET, timeout: float | UnsetType = UNSET) -> WaitForTimeoutResponse

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

wait_for_request​

wait_for_request(url: str | UnsetType = UNSET, *, method: Method | UnsetType = UNSET, operator: OperatorType | UnsetType = UNSET, timeout: float | UnsetType = UNSET) -> WaitForRequestResponse

wait_for_response​

wait_for_response(url: str | UnsetType = UNSET, *, statuses: Sequence[int] | UnsetType = UNSET, codes: Sequence[int] | UnsetType = UNSET, operator: OperatorType | UnsetType = UNSET, timeout: float | UnsetType = UNSET) -> WaitForResponseResponse

wait_for_selector​

wait_for_selector(selector: str, *, timeout: float | UnsetType = UNSET, visible: bool | UnsetType = UNSET, hidden: bool | UnsetType = UNSET) -> WaitForSelectorResponse

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

wait_for_timeout​

wait_for_timeout(ms: float) -> None

watch_event​

watch_event(event: str) -> WaitForEvent

Start tracking event now so a later wait_for_event call can return immediately if that event has already fired.

Was this page helpful?