page - Stagehand

A Page combines deterministic browser controls with Stagehand’s natural-language act, observe, and extract methods. Navigation methods return the main-document Response, when the navigation produces one.

TypeScript
Python
Go

Quick start

const page = await browser.context.newPage();
const response = await page.goto("https://example.com");

goto()

Navigate the page to a URL.

const response = await page.goto("https://example.com");

string

The destination URL.

PageNavigationOptions

Options that configure this operation.

number

Maximum wait time in milliseconds.

LoadState

The target load state: "load", "domcontentloaded", or "networkidle". Defaults to "domcontentloaded".

Promise<Response | null>

The final main-document response, or null when no network response was produced.

reload()

Reload the current page.

await page.reload();

PageReloadOptions

Options that configure this operation.

boolean

Whether to bypass the browser cache.

number

Maximum wait time in milliseconds.

LoadState

The target load state: "load", "domcontentloaded", or "networkidle". Defaults to "domcontentloaded".

Promise<Response | null>

The final main-document response, or null when no network response was produced.

goBack()

Navigate backward in the page history.

await page.goBack();

PageNavigationOptions

Options that configure this operation.

number

Maximum wait time in milliseconds.

LoadState

The target load state: "load", "domcontentloaded", or "networkidle". Defaults to "domcontentloaded".

Promise<Response | null>

The final main-document response, or null when no history navigation occurred or no network response was produced.

goForward()

Navigate forward in the page history.

await page.goForward();

PageNavigationOptions

Options that configure this operation.

number

Maximum wait time in milliseconds.

LoadState

The target load state: "load", "domcontentloaded", or "networkidle". Defaults to "domcontentloaded".

Promise<Response | null>

The final main-document response, or null when no history navigation occurred or no network response was produced.

click()

Click at page coordinates.

await page.click(240, 320);

number

The horizontal page coordinate.

number

The vertical page coordinate.

PageClickOptions

Options that configure this operation.

MouseButton

The mouse button to use: "left", "middle", or "right".

number

The number of clicks to dispatch.

Promise<void>

Resolves after the operation completes.

hover()

Move the pointer to page coordinates.

await page.hover(240, 320);

number

The horizontal page coordinate.

number

The vertical page coordinate.

Promise<void>

Resolves after the operation completes.

scroll()

Scroll from page coordinates by the supplied deltas.

await page.scroll(240, 320, 0, 600);

number

The horizontal page coordinate.

number

The vertical page coordinate.

number

Horizontal scroll distance.

number

Vertical scroll distance.

Promise<void>

Resolves after the operation completes.

dragAndDrop()

Drag from one page coordinate to another.

await page.dragAndDrop(100, 100, 400, 400);

number

The drag origin’s horizontal coordinate.

number

The drag origin’s vertical coordinate.

number

The drop target’s horizontal coordinate.

number

The drop target’s vertical coordinate.

PageDragAndDropOptions

Options that configure this operation.

MouseButton

The mouse button to use: "left", "middle", or "right".

number

The input delay in milliseconds.

number

The number of intermediate pointer moves.

PageDragAndDropRoutePoint[]

An ordered mouse route to follow instead of generating linear intermediate moves. The explicit toX and toY coordinates remain the final point.

number

A route point’s horizontal coordinate.

number

A route point’s vertical coordinate.

Promise<void>

Resolves after the operation completes.

type()

Type text at the current input target.

await page.type("Browserbase");

string

The text to type.

PageTypeOptions

Options that configure this operation.

number

The input delay in milliseconds.

boolean

Whether to simulate occasional typing mistakes.

Promise<void>

Resolves after the operation completes.

keyPress()

Send a keyboard key press to the page.

await page.keyPress("Enter");

string

The keyboard key to send.

PageKeyPressOptions

Options that configure this operation.

number

The input delay in milliseconds.

Promise<void>

Resolves after the operation completes.

evaluate()

Evaluate JavaScript in the page and return its result.

const title = await page.evaluate(() => document.title);

string | ((arg: Arg) => R | Promise<R>)

JavaScript source or a function to evaluate.

Arg

An optional argument passed to the function.

Promise<R>

The operation result.

on()

Subscribe to console messages from this page and its page-owned sessions. Stagehand delivers each message using the underlying "Runtime.consoleAPICalled" event envelope.

const subscription = await page.on("console", (event) => {
  console.log(event.method, event.params);
});

await page.evaluate(() => console.log("ready"));
await subscription.unsubscribe();

PageEventName

The console event name. Currently, the only supported value is "console".

PageEventListener

A callback that receives the event method, raw parameters, session ID, target ID, and page ID. Async callbacks may overlap and are not awaited by later page calls.

Promise<CDPSubscription>

A subscription handle whose unsubscribe() method stops delivery.

CDPSubscription

unsubscribe(): Promise<void> removes the listener locally and from the Stagehand runtime. Repeated calls share the completed cleanup. A failed runtime request can be retried by calling unsubscribe() again.

onToolsAdded()

Run a callback when WebMCP tools are added to this page or its child frames. The subscription reports future additions without replaying tools already registered. Use page.tools() to retrieve the current tools, or subscribe before navigation to receive tools from the new document. Subscriptions remain active across navigation.

const subscription = await page.onToolsAdded((tools) => {
  for (const tool of tools) {
    console.log(tool.name, tool.frameId, tool.inputSchema);
  }
});

await page.goto("https://stagehand-eval-sites.vercel.app/sites/webmcp-test/");
await subscription.unsubscribe();

ToolsAddedListener

A callback with the signature (tools: WebMCPTool[]) => unknown. Each call receives an array of added tools. Each tool exposes name, description, frameId, optional inputSchema, annotations, and backendNodeId, and an invoke() method. See the WebMCP reference for property types and invocation options. Async callbacks may overlap and are not awaited by later page calls.

Promise<CDPSubscription>

A subscription handle whose unsubscribe() method stops delivery. See CDPSubscription for cleanup behavior.

Tools are identified by frameId and name. A tool is also reported when its descriptor changes; an identical descriptor is not reported again.

onToolsRemoved()

Run a callback when WebMCP tools are removed from this page or its child frames. Removals include tools unregistered by the page and tools cleared when their document navigates or their frame detaches. The subscription reports future removals and remains active across navigation.

await page.goto("https://stagehand-eval-sites.vercel.app/sites/webmcp-test/");
const subscription = await page.onToolsRemoved((tools) => {
  for (const tool of tools) {
    console.log(tool.name, tool.frameId);
  }
});

await page.goto("about:blank");
await subscription.unsubscribe();

ToolsRemovedListener

A callback with the signature (tools: WebMCPToolIdentity[]) => unknown. Each call receives an array of removed tool identities containing name and frameId, both strings. These identities have no invoke() method. Async callbacks may overlap and are not awaited by later page calls.

Promise<CDPSubscription>

A subscription handle whose unsubscribe() method stops delivery. See CDPSubscription for cleanup behavior.

addInitScript()

Run a script before other scripts whenever the page navigates.

await page.addInitScript(() => {
  window.localStorage.clear();
});

InitScriptSource<Arg>

A function, JavaScript source string, or object with exactly one of path and content.

Arg

An optional JSON-serializable argument. Valid only when script is a function.

Promise<void>

Resolves after the operation completes.

setExtraHTTPHeaders()

Set additional HTTP headers for this page.

await page.setExtraHTTPHeaders({ "x-test": "true" });

Record<string, string>

HTTP header names and values.

Promise<void>

Resolves after the operation completes.

setViewportSize()

Set the page viewport dimensions.

await page.setViewportSize(1440, 900);

number

Viewport width in CSS pixels.

number

Viewport height in CSS pixels.

PageSetViewportSizeOptions

Options that configure this operation.

number

The device scale factor.

Promise<void>

Resolves after the operation completes.

waitForLoadState()

Wait until the page reaches a load state.

await page.waitForLoadState("networkidle", 10_000);

LoadState

The state to wait for: "load", "domcontentloaded", or "networkidle".

number

Maximum wait time in milliseconds.

Promise<void>

Resolves after the operation completes.

waitForTimeout()

Wait for a fixed number of milliseconds.

await page.waitForTimeout(500);

number

The number of milliseconds to wait.

Promise<void>

Resolves after the operation completes.

waitForSelector()

Wait for a selector to reach the requested state.

const matched = await page.waitForSelector("main");

string

The selector to target.

PageWaitForSelectorOptions

Options that configure this operation.

boolean

Whether to traverse shadow roots. Closed roots require a navigated page; see the locator reference.

PageWaitForSelectorOptions['state']

The state to wait for: "attached", "detached", "visible", or "hidden".

number

Timeout in milliseconds, including frame readiness. Defaults to 30000; 0 disables the timeout.

Promise<boolean>

The operation result.

screenshot()

Capture a screenshot of the page.

const image = await page.screenshot({ fullPage: true });

ScreenshotOptions

Options that configure this operation.

ScreenshotOptions['animations']

How to handle active animations: "disabled" or "allow".

ScreenshotOptions['caret']

How to render the text caret: "hide" or "initial".

PageScreenshotClip

The screenshot crop rectangle.

number

The positive height in CSS pixels.

number

The positive width in CSS pixels.

number

The horizontal coordinate.

number

The vertical coordinate.

boolean

Whether to capture the full scrollable page. Cannot be combined with clip.

Locator[]

Page-created locators for elements to obscure. Every locator must belong to this page.

string

The CSS mask color.

boolean

Whether to use a transparent background.

string

A file path where the image is also written.

number

JPEG quality as an integer from 0 to 100. Valid only when type is "jpeg".

ScreenshotOptions['scale']

Whether to use "css" or "device" pixel scale.

string

CSS applied while taking the screenshot.

number

The non-negative operation timeout in milliseconds.

ScreenshotOptions['type']

The image format: "png" or "jpeg".

Promise<Uint8Array>

The screenshot image bytes.

pdf()

Render the current document to PDF with Chrome’s print pipeline.If a running print times out, further captures on that page fail until Chrome finishes the pending print. Other pages remain available.

const pdf = await page.pdf({
  path: "page.pdf",
  margin: { top: 0.25, bottom: 0.25 },
  preferCSSPageSize: true,
  printBackground: true,
});

PDFOptions

Options that configure PDF rendering. Paper sizes and margins are measured in inches.

boolean

Whether to render the header and footer templates.

string

HTML for the print footer. Chrome fills elements with pageNumber, totalPages, date, title, and url classes.

boolean

Whether to generate a document outline from the page structure. Defaults to false.

boolean

Whether to include document structure tags in the PDF. Defaults to false.

string

HTML for the print header, with the same supported classes as footerTemplate.

boolean

Whether to use landscape orientation.

PagePDFMargin

Non-negative page margins in inches. Each omitted side defaults to 0.

number

string

Page ranges to print, such as "1-3, 5".

number

The positive paper height in inches.

number

The positive paper width in inches.

string

A local file path where the PDF is also written. Node.js only.

boolean

Whether CSS @page sizing takes precedence over width and height.

boolean

Whether to include CSS backgrounds.

number

Render scale from 0.1 to 2.

number

Maximum capture wait in milliseconds, including time queued behind another capture. Defaults to 30000; 0 disables the deadline. Must be between 0 and 2147473647.

Promise<Uint8Array>

The PDF bytes.

snapshot()

Capture the page’s accessibility-oriented DOM snapshot.

const snapshot = await page.snapshot();

PageSnapshotOptions

Options that configure this operation.

boolean

Whether to include iframe content.

number

Maximum time in milliseconds for the whole snapshot, including frame traversal & browser reads. Defaults to 20,000 ms. Use 0 for no timeout. Request delivery is outside this budget.

Promise<SnapshotResult>

The operation result.

string

The formatted page tree.

object

The snapshot URL lookup.

object

The snapshot XPath lookup.

tools()

Return the WebMCP tools registered on the page.

const tools = await page.tools();

const searchTool = tools.find((tool) => tool.name === "search");
if (!searchTool) throw new Error("Search tool is unavailable");

console.log(searchTool.inputSchema);

const invocation = await searchTool.invoke({
  input: { query: "Stagehand" },
});
const result = await invocation.result();
console.log(result.status, result.output);

WebMCPToolsOptions

Options that configure tool discovery.

number

Maximum time in milliseconds to wait for registered tools.

Promise<WebMCPTool[]>

The callable WebMCP tools registered on the page. See the WebMCP reference.

url()

Return the page’s current URL.

const url = await page.url();

Promise<string>

The operation result.

title()

Return the page’s current document title.

const title = await page.title();

Promise<string>

The operation result.

close()

Close the page.

await page.close();

Promise<void>

Resolves after the operation completes.

locator()

Create a locator for a CSS selector on this page.

const locator = page.locator("button[type=submit]");

string

The selector to target.

Locator

The operation result.

Quick start

page = await browser.context.new_page()
response = await page.goto("https://example.com")

goto()

Navigate the page to a URL.

response = await page.goto("https://example.com")

str

The destination URL.

LoadState | Literal['load', 'domcontentloaded', 'networkidle']

The load state to wait for. Defaults to "domcontentloaded".

int | None

Maximum wait time in milliseconds.

Response | None

The final main-document response, or None when no network response was produced.

reload()

Reload the current page.

await page.reload()

LoadState | Literal['load', 'domcontentloaded', 'networkidle']

The load state to wait for. Defaults to "domcontentloaded".

int | None

Maximum wait time in milliseconds.

bool | None

Whether to bypass the browser cache.

Response | None

The final main-document response, or None when no network response was produced.

go_back()

Navigate backward in the page history.

await page.go_back()

LoadState | Literal['load', 'domcontentloaded', 'networkidle']

The load state to wait for. Defaults to "domcontentloaded".

int | None

Maximum wait time in milliseconds.

Response | None

The final main-document response, or None when no history navigation occurred or no network response was produced.

go_forward()

Navigate forward in the page history.

await page.go_forward()

LoadState | Literal['load', 'domcontentloaded', 'networkidle']

The load state to wait for. Defaults to "domcontentloaded".

int | None

Maximum wait time in milliseconds.

Response | None

The final main-document response, or None when no history navigation occurred or no network response was produced.

click()

Click at page coordinates.

await page.click(240, 320)

float

The horizontal page coordinate.

float

The vertical page coordinate.

MouseButton | Literal['left', 'right', 'middle']

The mouse button to use.

int | None

The number of clicks to dispatch.

None

Resolves after the operation completes.

hover()

Move the pointer to page coordinates.

await page.hover(240, 320)

float

The horizontal page coordinate.

float

The vertical page coordinate.

None

Resolves after the operation completes.

scroll()

Scroll from page coordinates by the supplied deltas.

await page.scroll(240, 320, 0, 600)

float

The horizontal page coordinate.

float

The vertical page coordinate.

float

Horizontal scroll distance.

float

Vertical scroll distance.

None

Resolves after the operation completes.

drag_and_drop()

Drag from one page coordinate to another.

await page.drag_and_drop(100, 100, 400, 400)

float

The drag origin’s horizontal coordinate.

float

The drag origin’s vertical coordinate.

float

The drop target’s horizontal coordinate.

float

The drop target’s vertical coordinate.

MouseButton | Literal['left', 'right', 'middle']

The mouse button to use.

int | None

The number of intermediate pointer moves.

float | None

An optional input delay in milliseconds.

Sequence[PageDragAndDropRoutePoint | Mapping[str, float]] | None

An ordered mouse route to follow instead of generating linear intermediate moves. The explicit to_x and to_y coordinates remain the final point.

float

A route point’s horizontal coordinate.

float

A route point’s vertical coordinate.

None

Resolves after the operation completes.

type()

Type text at the current input target.

await page.type("Browserbase")

str

The text to type.

float | None

An optional input delay in milliseconds.

bool | None

Whether to simulate occasional typing mistakes.

None

Resolves after the operation completes.

key_press()

Send a keyboard key press to the page.

await page.key_press("Enter")

str

The keyboard key to send.

float | None

An optional input delay in milliseconds.

None

Resolves after the operation completes.

evaluate()

Evaluate JavaScript in the page and return its result.

title = await page.evaluate("document.title", result_type=str)

str

JavaScript source or a function to evaluate.

type[EvaluateResult] | None

An optional Python type used to validate the result.

JsonValue | EvaluateResult

The operation result.

on()

Subscribe to console messages from this page and its page-owned sessions. Stagehand delivers each message using the underlying "Runtime.consoleAPICalled" event envelope.

async def handle_console(event: PageCDPEvent) -> None:
    print(event.method, event.params)

subscription = await page.on("console", handle_console)
await page.evaluate('console.log("ready")')
await subscription.unsubscribe()

PageEventName

The console event name. Currently, the only supported value is "console".

PageEventListener

A sync or async callback that receives the event method, raw parameters, session ID, target ID, and page ID. Async callbacks may overlap and are not awaited by later page calls.

CDPSubscription

A subscription handle whose unsubscribe() method stops delivery.

CDPSubscription

await subscription.unsubscribe() removes the listener locally and from the Stagehand runtime. Repeated calls await the same successful cleanup. Failed cleanup can be retried. If the caller is cancelled while awaiting cleanup, the shared cleanup task continues in the background.

on_tools_added()

def handle_tools_added(tools: list[WebMCPTool]) -> None:
    for tool in tools:
        print(tool.name, tool.frame_id, tool.input_schema)

subscription = await page.on_tools_added(handle_tools_added)
await page.goto("https://stagehand-eval-sites.vercel.app/sites/webmcp-test/")
await subscription.unsubscribe()

ToolsAddedListener

A sync or async callback that receives a list[WebMCPTool] of added tools. Each tool exposes name, description, frame_id, optional input_schema, annotations, and backend_node_id, and an invoke() method. See the WebMCP reference for property types and invocation options. Async callbacks may overlap and are not awaited by later page calls.

CDPSubscription

A subscription handle whose unsubscribe() method removes the listener locally and from the Stagehand runtime. Repeated calls await the same successful cleanup; failed cleanup can be retried.

Tools are identified by frame_id and name. A tool is also reported when its descriptor changes; an identical descriptor is not reported again.

on_tools_removed()

await page.goto("https://stagehand-eval-sites.vercel.app/sites/webmcp-test/")

def handle_tools_removed(tools: list[WebMCPToolIdentity]) -> None:
    for tool in tools:
        print(tool.name, tool.frame_id)

subscription = await page.on_tools_removed(handle_tools_removed)
await page.goto("about:blank")
await subscription.unsubscribe()

ToolsRemovedListener

A sync or async callback that receives a list[WebMCPToolIdentity] of removed tool identities containing name and frame_id, both strings. These identities have no invoke() method. Async callbacks may overlap and are not awaited by later page calls.

CDPSubscription

A subscription handle whose unsubscribe() method removes the listener locally and from the Stagehand runtime. Repeated calls await the same successful cleanup; failed cleanup can be retried.

add_init_script()

Run a script before other scripts whenever the page navigates.

await page.add_init_script("window.localStorage.clear()")

str | Path

JavaScript source or a path to a JavaScript file on the SDK caller’s machine.

None

Resolves after the operation completes.

set_extra_http_headers()

Set additional HTTP headers for this page.

await page.set_extra_http_headers({"x-test": "true"})

Mapping[str, str]

HTTP header names and values.

None

Resolves after the operation completes.

set_viewport_size()

Set the page viewport dimensions.

await page.set_viewport_size(1440, 900)

int

Viewport width in CSS pixels.

int

Viewport height in CSS pixels.

float | None

The device scale factor.

None

Resolves after the operation completes.

wait_for_load_state()

Wait until the page reaches a load state.

await page.wait_for_load_state("networkidle", timeout=10_000)

LoadState | Literal['load', 'domcontentloaded', 'networkidle']

The state to wait for: "load", "domcontentloaded", or "networkidle".

int | None

Maximum wait time in milliseconds.

None

Resolves after the operation completes.

wait_for_timeout()

Wait for a fixed number of milliseconds.

await page.wait_for_timeout(500)

int

The number of milliseconds to wait.

None

Resolves after the operation completes.

wait_for_selector()

Wait for a selector to reach the requested state.

matched = await page.wait_for_selector("main", state="visible")

str

The selector to target.

State | Literal['attached', 'detached', 'visible', 'hidden']

The state to wait for: "attached", "detached", "visible", or "hidden".

int | None

Timeout in milliseconds, including frame readiness. Defaults to 30000; 0 disables the timeout.

bool | None

Whether to traverse shadow roots. Closed roots require a navigated page; see the locator reference.

bool

The operation result.

screenshot()

Capture a screenshot of the page.

image = await page.screenshot(full_page=True)

Animations | Literal['disabled', 'allow']

How to handle CSS animations: "disabled" or "allow".

Caret | Literal['hide', 'initial']

How to render the text caret: "hide" or "initial".

PageScreenshotClip | None

The region to capture.

float

The positive height in CSS pixels.

float

The positive width in CSS pixels.

float

The horizontal coordinate.

float

The vertical coordinate.

bool | None

Whether to capture the full scrollable page. Cannot be combined with clip.

str | Path | None

A path where the image is also written.

Sequence[Locator] | None

Page-created locators for elements to obscure. Every locator must belong to this page.

str | None

The CSS color used for masks.

bool | None

Whether to use a transparent background.

int | None

JPEG quality as an integer from 0 to 100. Valid only when type is "jpeg".

Scale | Literal['css', 'device']

Whether to use "css" or "device" pixel scale.

str | None

CSS applied while taking the screenshot.

float | None

Maximum non-negative wait time in milliseconds.

ScreenshotType | Literal['png', 'jpeg']

The image format: "png" or "jpeg".

bytes

The operation result.

pdf()

pdf = await page.pdf(
    path="page.pdf",
    margin={"top": 0.25, "bottom": 0.25},
    prefer_css_page_size=True,
    print_background=True,
)

Paper dimensions and margins are measured in inches.

bool | None

Whether to render the header and footer templates.

str | None

HTML for the print footer. Chrome fills elements with pageNumber, totalPages, date, title, and url classes.

bool | None

Whether to generate a document outline from the page structure. Defaults to False.

bool | None

Whether to include document structure tags in the PDF. Defaults to False.

str | None

HTML for the print header, with the same supported classes as footer_template.

bool | None

PagePDFMargin | None

Non-negative page margins in inches. Each omitted side defaults to 0.

float

str | None

Page ranges to print, such as "1-3, 5".

float | None

The positive paper height in inches.

float | None

The positive paper width in inches.

str | Path | None

A local path where the PDF is also written.

bool | None

Whether CSS @page sizing takes precedence over width and height.

bool | None

Whether to include CSS backgrounds.

float | None

Render scale from 0.1 to 2.

float | None

Maximum capture wait in milliseconds, including time queued behind another capture. Defaults to 30000; 0 disables the deadline. Must be between 0 and 2147473647.

bytes

The PDF bytes.

snapshot()

Capture the page’s accessibility-oriented DOM snapshot.

snapshot = await page.snapshot()

bool | None

Whether to include iframe content.

float | None

Maximum time in milliseconds for the whole snapshot, including frame traversal & browser reads. Defaults to 20,000 ms. Use 0 for no timeout. Request delivery is outside this budget.

SnapshotResult

The operation result.

str

The formatted page tree.

dict[str, object]

The snapshot URL lookup.

dict[str, object]

The snapshot XPath lookup.

tools()

Return the WebMCP tools registered on the page.

tools = await page.tools()

search_tool = next((tool for tool in tools if tool.name == "search"), None)
if search_tool is None:
    raise RuntimeError("Search tool is unavailable")

print(search_tool.input_schema)

invocation = await search_tool.invoke(input={"query": "Stagehand"})
result = await invocation.result()
print(result.status, result.output)

float | None

Maximum time in milliseconds to wait for registered tools.

list[WebMCPTool]

The callable WebMCP tools registered on the page. See the WebMCP reference.

url()

Return the page’s current URL.

url = await page.url()

str

The operation result.

title()

Return the page’s current document title.

title = await page.title()

str

The operation result.

close()

Close the page.

await page.close()

None

Resolves after the operation completes.

locator()

Create a locator for a CSS selector on this page.

locator = page.locator("button[type=submit]")

str

The selector to target.

Locator

The operation result.

Quick start

browserContext, err := browser.Context()
if err != nil {
    return err
}
page, err := browserContext.NewPage(ctx)
if err != nil {
    return err
}
if _, err := page.Goto(ctx, "https://example.com", nil); err != nil {
    return err
}

Every method that talks to the browser takes a context.Context first and returns an error last; the local Locator() accessor takes neither. Options are passed as pointer structs; pass nil for defaults.

Goto()

Navigate the page to a URL.

if _, err := page.Goto(ctx, "https://example.com", nil); err != nil {
    return err
}

string

The destination URL.

*PageNavigationOptions

Options that configure this operation. Pass nil for defaults.

*int

Maximum wait time in milliseconds.

*LoadState

The target load state: LoadStateLoad, LoadStateDOMContentLoaded, or LoadStateNetworkIdle. Defaults to LoadStateDOMContentLoaded.

(*Response, error)

The final main-document response, or nil when no network response was produced.

Reload()

Reload the current page.

if _, err := page.Reload(ctx, nil); err != nil {
    return err
}

*PageReloadOptions

Options that configure this operation. Pass nil for defaults.

*bool

Whether to bypass the browser cache.

*int

Maximum wait time in milliseconds.

*LoadState

The target load state: LoadStateLoad, LoadStateDOMContentLoaded, or LoadStateNetworkIdle. Defaults to LoadStateDOMContentLoaded.

(*Response, error)

The final main-document response, or nil when no network response was produced.

GoBack()

Navigate backward in the page history.

if _, err := page.GoBack(ctx, nil); err != nil {
    return err
}

*PageNavigationOptions

Options that configure this operation. Pass nil for defaults.

*int

Maximum wait time in milliseconds.

*LoadState

The target load state: LoadStateLoad, LoadStateDOMContentLoaded, or LoadStateNetworkIdle. Defaults to LoadStateDOMContentLoaded.

(*Response, error)

The final main-document response, or nil when no history navigation occurred or no network response was produced.

GoForward()

Navigate forward in the page history.

if _, err := page.GoForward(ctx, nil); err != nil {
    return err
}

*PageNavigationOptions

Options that configure this operation. Pass nil for defaults.

*int

Maximum wait time in milliseconds.

*LoadState

The target load state: LoadStateLoad, LoadStateDOMContentLoaded, or LoadStateNetworkIdle. Defaults to LoadStateDOMContentLoaded.

(*Response, error)

The final main-document response, or nil when no history navigation occurred or no network response was produced.

Click()

Click at page coordinates.

if err := page.Click(ctx, 240, 320, nil); err != nil {
    return err
}

float64

The horizontal page coordinate.

float64

The vertical page coordinate.

*PageClickOptions

Options that configure this operation. Pass nil for defaults.

*MouseButton

The mouse button to use: MouseButtonLeft, MouseButtonMiddle, or MouseButtonRight.

*int

The number of clicks to dispatch.

error

Returns nil after the operation completes.

Hover()

Move the pointer to page coordinates.

if err := page.Hover(ctx, 240, 320); err != nil {
    return err
}

float64

The horizontal page coordinate.

float64

The vertical page coordinate.

error

Returns nil after the operation completes.

Scroll()

Scroll from page coordinates by the supplied deltas.

if err := page.Scroll(ctx, 240, 320, 0, 600); err != nil {
    return err
}

float64

The horizontal page coordinate.

float64

The vertical page coordinate.

float64

Horizontal scroll distance.

float64

Vertical scroll distance.

error

Returns nil after the operation completes.

DragAndDrop()

Drag from one page coordinate to another.

if err := page.DragAndDrop(ctx, 100, 100, 400, 400, nil); err != nil {
    return err
}

float64

The drag origin’s horizontal coordinate.

float64

The drag origin’s vertical coordinate.

float64

The drop target’s horizontal coordinate.

float64

The drop target’s vertical coordinate.

*PageDragAndDropOptions

Options that configure this operation. Pass nil for defaults.

*MouseButton

The mouse button to use: MouseButtonLeft, MouseButtonMiddle, or MouseButtonRight.

*float64

The input delay in milliseconds.

*int

The number of intermediate pointer moves.

[]PageDragAndDropRoutePoint

An ordered mouse route to follow instead of generating linear intermediate moves. The explicit toX and toY coordinates remain the final point.

float64

A route point’s horizontal coordinate.

float64

A route point’s vertical coordinate.

error

Returns nil after the operation completes.

Type()

Type text at the current input target.

if err := page.Type(ctx, "Browserbase", nil); err != nil {
    return err
}

string

The text to type.

*PageTypeOptions

Options that configure this operation. Pass nil for defaults.

*float64

The input delay in milliseconds.

*bool

Whether to simulate occasional typing mistakes.

error

Returns nil after the operation completes.

KeyPress()

Send a keyboard key press to the page.

if err := page.KeyPress(ctx, "Enter", nil); err != nil {
    return err
}

string

The keyboard key to send.

*PageKeyPressOptions

Options that configure this operation. Pass nil for defaults.

*float64

The input delay in milliseconds.

error

Returns nil after the operation completes.

Evaluate()

Evaluate JavaScript in the page and return its result. Evaluate returns the raw JSON value; use the package-level generic EvaluateAs to decode the result into a Go type.

title, err := stagehand.EvaluateAs[string](ctx, page, "document.title")
if err != nil {
    return err
}
fmt.Println(title)

string

JavaScript source to evaluate.

(json.RawMessage, error)

The operation result as raw JSON. EvaluateAs[T] decodes it into T instead.

On()

Subscribe to console messages from this page and its page-owned sessions. Stagehand delivers each message using the underlying "Runtime.consoleAPICalled" event envelope.

subscription, err := page.On(ctx, stagehand.PageEventNameConsole, func(event stagehand.PageCDPEvent) {
    fmt.Println(event.Method, event.Params)
})
if err != nil {
    return err
}

if _, err := page.Evaluate(ctx, `console.log("ready")`); err != nil {
    return err
}
if err := subscription.Close(ctx); err != nil {
    return err
}

PageEventName

The console event name. Currently, the only supported value is PageEventNameConsole.

func(PageCDPEvent)

A callback that receives the event method, raw parameters, session ID, target ID, and page ID. Listeners are not awaited by later page calls.

(*CDPSubscription, error)

A subscription handle whose Close() method stops delivery.

CDPSubscription

Close(ctx context.Context) error removes the listener locally and from the Stagehand runtime. Repeated calls after successful cleanup return nil. Concurrent calls share the active cleanup; a failed attempt can be retried.

OnToolsAdded()

Run a callback when WebMCP tools are added to this page or its child frames. The subscription reports future additions without replaying tools already registered. Use page.Tools(ctx, nil) to retrieve the current tools, or subscribe before navigation to receive tools from the new document. Subscriptions remain active across navigation.

subscription, err := page.OnToolsAdded(ctx, func(tools []*stagehand.WebMCPTool) {
    for _, tool := range tools {
        descriptor := tool.Descriptor()
        fmt.Println(descriptor.Name, descriptor.FrameID, descriptor.InputSchema)
    }
})
if err != nil {
    return err
}

if _, err := page.Goto(ctx, "https://stagehand-eval-sites.vercel.app/sites/webmcp-test/", nil); err != nil {
    return err
}
if err := subscription.Close(ctx); err != nil {
    return err
}

func([]*WebMCPTool)

A non-nil callback that receives a slice of added tools. Each tool exposes its descriptor through Descriptor() and can be invoked with Invoke(). See the WebMCP reference for descriptor fields and invocation options. Listeners are not awaited by later page calls.

(*CDPSubscription, error)

A subscription handle whose Close(ctx) method removes the listener locally and from the Stagehand runtime. Repeated calls after successful cleanup return nil; failed cleanup can be retried.

Tools are identified by FrameID and Name. A tool is also reported when its descriptor changes; an identical descriptor is not reported again.

OnToolsRemoved()

if _, err := page.Goto(ctx, "https://stagehand-eval-sites.vercel.app/sites/webmcp-test/", nil); err != nil {
    return err
}
subscription, err := page.OnToolsRemoved(ctx, func(tools []stagehand.WebMCPToolIdentity) {
    for _, tool := range tools {
        fmt.Println(tool.Name, tool.FrameID)
    }
})
if err != nil {
    return err
}

if _, err := page.Goto(ctx, "about:blank", nil); err != nil {
    return err
}
if err := subscription.Close(ctx); err != nil {
    return err
}

func([]WebMCPToolIdentity)

A non-nil callback that receives a slice of removed tool identities containing Name and FrameID, both strings. These identities have no Invoke() method. Listeners are not awaited by later page calls.

(*CDPSubscription, error)

A subscription handle whose Close(ctx) method removes the listener locally and from the Stagehand runtime. Repeated calls after successful cleanup return nil; failed cleanup can be retried.

AddInitScript()

Run a script before other scripts whenever the page navigates.

if err := page.AddInitScript(ctx, "window.localStorage.clear()"); err != nil {
    return err
}

string

JavaScript source. Go functions and file paths are not interpreted.

error

Returns nil after the operation completes.

SetExtraHTTPHeaders()

Set additional HTTP headers for this page.

headers := stagehand.PageSetExtraHTTPHeadersParamsHeaders{"x-test": "true"}
if err := page.SetExtraHTTPHeaders(ctx, headers); err != nil {
    return err
}

PageSetExtraHTTPHeadersParamsHeaders

HTTP header names and values, as a map[string]string.

error

Returns nil after the operation completes.

SetViewportSize()

Set the page viewport dimensions.

if err := page.SetViewportSize(ctx, 1440, 900, nil); err != nil {
    return err
}

int

Viewport width in CSS pixels.

int

Viewport height in CSS pixels.

*PageSetViewportSizeOptions

Options that configure this operation. Pass nil for defaults.

*float64

The device scale factor.

error

Returns nil after the operation completes.

WaitForLoadState()

Wait until the page reaches a load state.

timeout := 10_000
if err := page.WaitForLoadState(ctx, stagehand.LoadStateNetworkIdle, &timeout); err != nil {
    return err
}

LoadState

The state to wait for: LoadStateLoad, LoadStateDOMContentLoaded, or LoadStateNetworkIdle.

*int

Maximum wait time in milliseconds. Pass nil for the default.

error

Returns nil after the operation completes.

WaitForTimeout()

Wait for a fixed number of milliseconds.

if err := page.WaitForTimeout(ctx, 500); err != nil {
    return err
}

int

The number of milliseconds to wait.

error

Returns nil after the operation completes.

WaitForSelector()

Wait for a selector to reach the requested state.

matched, err := page.WaitForSelector(ctx, "main", nil)
if err != nil {
    return err
}
fmt.Println(matched)

string

The selector to target.

*PageWaitForSelectorOptions

Options that configure this operation. Pass nil for defaults.

*bool

Whether to traverse shadow roots. Closed roots require a navigated page; see the locator reference.

*PageWaitForSelectorOptionsState

The state to wait for: PageWaitForSelectorOptionsStateAttached, PageWaitForSelectorOptionsStateDetached, PageWaitForSelectorOptionsStateVisible, or PageWaitForSelectorOptionsStateHidden.

*int

Timeout in milliseconds, including frame readiness. Defaults to 30000; 0 disables the timeout.

(bool, error)

The operation result.

Screenshot()

Capture a screenshot of the page. There is no path option in Go; write the returned bytes yourself, for example with os.WriteFile.

fullPage := true
image, err := page.Screenshot(ctx, &stagehand.ScreenshotOptions{FullPage: &fullPage})
if err != nil {
    return err
}
if err := os.WriteFile("screenshot.png", image, 0o644); err != nil {
    return err
}

*ScreenshotOptions

Options that configure this operation. Pass nil for defaults.

*PageScreenshotOptionsAnimations

How to handle active animations: PageScreenshotOptionsAnimationsDisabled or PageScreenshotOptionsAnimationsAllow.

*PageScreenshotOptionsCaret

How to render the text caret: PageScreenshotOptionsCaretHide or PageScreenshotOptionsCaretInitial.

*PageScreenshotClip

The screenshot crop rectangle.

float64

The positive height in CSS pixels.

float64

The positive width in CSS pixels.

float64

The horizontal coordinate.

float64

The vertical coordinate.

*bool

Whether to capture the full scrollable page. Cannot be combined with options.Clip.

[]*PageLocator

Page-created locators for elements to obscure in the screenshot. Create each with page.Locator("..."); every mask locator must belong to the page being captured.

*string

The CSS mask color.

*bool

Whether to use a transparent background.

*int

JPEG quality as an integer from 0 to 100. Valid only when options.Type is PageScreenshotOptionsTypeJPEG.

*PageScreenshotOptionsScale

Whether to use PageScreenshotOptionsScaleCSS or PageScreenshotOptionsScaleDevice.

*string

CSS applied while taking the screenshot.

*float64

The non-negative operation timeout in milliseconds.

*PageScreenshotOptionsType

The image format: PageScreenshotOptionsTypePNG or PageScreenshotOptionsTypeJPEG.

([]byte, error)

The screenshot image bytes.

PDF()

Render the current document to PDF with Chrome’s print pipeline. Write the returned bytes with os.WriteFile when a file is needed.If a running print times out, further captures on that page fail until Chrome finishes the pending print. Other pages remain available.

printBackground := true
pdf, err := page.PDF(ctx, &stagehand.PagePDFOptions{PrintBackground: &printBackground})
if err != nil {
    return err
}
if err := os.WriteFile("page.pdf", pdf, 0o644); err != nil {
    return err
}

*PagePDFOptions

Options that configure PDF rendering. Pass nil for defaults. Paper sizes and margins are measured in inches.

*bool

*string

*bool

Whether to generate a document outline from the page structure. Defaults to false.

*bool

Whether to include document structure tags in the PDF. Defaults to false.

*string

*bool

*PagePDFMargin

Non-negative page margins in inches. Each omitted side defaults to 0.

*float64

*string

*float64

The positive paper height in inches.

*float64

The positive paper width in inches.

*bool

Whether CSS @page sizing takes precedence over Width and Height.

*bool

*float64

Render scale from 0.1 to 2.

*float64

Maximum capture wait in milliseconds, including time queued behind another capture. Defaults to 30000; 0 disables the deadline. Must be between 0 and 2147473647. The caller’s context can end the wait earlier.

([]byte, error)

The PDF bytes.

Snapshot()

Capture the page’s accessibility-oriented DOM snapshot.

snapshot, err := page.Snapshot(ctx, nil)
if err != nil {
    return err
}
fmt.Println(snapshot.FormattedTree)

*PageSnapshotOptions

Options that configure this operation. Pass nil for defaults.

*bool

Whether to include iframe content.

*float64

Maximum time in milliseconds for the whole snapshot, including frame traversal & browser reads. Defaults to 20,000 ms. Use 0 for no timeout. Request delivery is outside this budget.

(SnapshotResult, error)

The operation result.

string

The formatted page tree.

SnapshotResultURLMap

The snapshot URL lookup.

SnapshotResultXPathMap

The snapshot XPath lookup.

Tools()

Return the WebMCP tools registered on the page.

tools, err := page.Tools(ctx, nil)
if err != nil {
    return err
}

var searchTool *stagehand.WebMCPTool
for _, tool := range tools {
    if tool.Descriptor().Name == "search" {
        searchTool = tool
        break
    }
}
if searchTool == nil {
    return errors.New("search tool is unavailable")
}

fmt.Println(searchTool.Descriptor().InputSchema)

invocation, err := searchTool.Invoke(ctx, stagehand.WebMCPInput{"query": "Stagehand"})
if err != nil {
    return err
}
result, err := invocation.Result(ctx, nil)
if err != nil {
    return err
}
fmt.Println(result.Status, result.Output)

*WebMCPToolsOptions

Options that configure tool discovery. Pass nil for defaults.

float64

Maximum time in milliseconds to wait for registered tools.

([]*WebMCPTool, error)

The callable WebMCP tools registered on the page. See the WebMCP reference.

URL()

Return the page’s current URL.

url, err := page.URL(ctx)
if err != nil {
    return err
}
fmt.Println(url)

(string, error)

The operation result.

Title()

Return the page’s current document title.

title, err := page.Title(ctx)
if err != nil {
    return err
}
fmt.Println(title)

(string, error)

The operation result.

Close()

Close the page.

if err := page.Close(ctx); err != nil {
    return err
}

error

Returns nil after the operation completes.

Locator()

Create a locator for a CSS selector on this page.

locator := page.Locator("button[type=submit]")
if err := locator.Click(ctx, nil); err != nil {
    return err
}

string

The selector to target.

*PageLocator

The operation result.

​Quick start

​goto()

​reload()

​goBack()

​goForward()

​click()

​hover()

​scroll()

​dragAndDrop()

​type()

​keyPress()

​evaluate()

​on()

​CDPSubscription

​onToolsAdded()

​onToolsRemoved()

​addInitScript()

​setExtraHTTPHeaders()

​setViewportSize()

​waitForLoadState()

​waitForTimeout()

​waitForSelector()

​screenshot()

​pdf()

​snapshot()

​tools()

​url()

​title()

​close()

​locator()

​Quick start

​goto()

​reload()

​go_back()

​go_forward()

​click()

​hover()

​scroll()

​drag_and_drop()

​type()

​key_press()

​evaluate()

​on()

​CDPSubscription

​on_tools_added()

​on_tools_removed()

​add_init_script()

​set_extra_http_headers()

​set_viewport_size()

​wait_for_load_state()

​wait_for_timeout()

​wait_for_selector()

​screenshot()

​pdf()

​snapshot()

​tools()

​url()

​title()

​close()

​locator()

​Quick start

​Goto()

​Reload()

​GoBack()

​GoForward()

​Click()

​Hover()

​Scroll()

​DragAndDrop()

​Type()

​KeyPress()

​Evaluate()

​On()

​CDPSubscription

​OnToolsAdded()

​OnToolsRemoved()

​AddInitScript()

​SetExtraHTTPHeaders()

​SetViewportSize()

​WaitForLoadState()

Quick start

goto()

reload()

goBack()

goForward()

click()

hover()

scroll()

dragAndDrop()

type()

keyPress()

evaluate()

on()

CDPSubscription

onToolsAdded()

onToolsRemoved()

addInitScript()

setExtraHTTPHeaders()

setViewportSize()

waitForLoadState()

waitForTimeout()

waitForSelector()

screenshot()

pdf()

snapshot()

tools()

url()

title()

close()

locator()

Quick start

goto()

reload()

go_back()

go_forward()

click()

hover()

scroll()

drag_and_drop()

type()

key_press()

evaluate()

on()

CDPSubscription

on_tools_added()

on_tools_removed()

add_init_script()

set_extra_http_headers()

set_viewport_size()

wait_for_load_state()

wait_for_timeout()

wait_for_selector()

screenshot()

pdf()

snapshot()

tools()

url()

title()

close()

locator()

Quick start

Goto()

Reload()

GoBack()

GoForward()

Click()

Hover()

Scroll()

DragAndDrop()

Type()

KeyPress()

Evaluate()

On()

CDPSubscription

OnToolsAdded()

OnToolsRemoved()

AddInitScript()

SetExtraHTTPHeaders()

SetViewportSize()

WaitForLoadState()