Browser RuntimeStagehand

Stagehand Page

View as Markdown

All Page methods available when using the Stagehand driver.

Access via runtime.page after launching a Stagehand runtime.

Every method below is a remote call. The SDK translates it into a structured step sent to a single endpoint:

POST /v1/workspaces/{workspaceId}/execute
1{
2  "runtime": "my-browser",
3  "steps": [
4    {
5      "call": "page.goto",
6      "args": ["https://example.com"]
7    }
8  ]
9}

The call field maps directly to the method name. args is a JSON array of the method’s arguments. You can batch multiple steps in one request.

goto(url, options?)

Navigate the page to a URL.

Options include:

  • waitUntil: ‘load’ | ‘domcontentloaded’ | ‘networkidle’
  • timeoutMs: Maximum navigation time in milliseconds
1await page.goto("https://example.com");
ParameterTypeRequiredDescription
urlstringYesURL to navigate to.
optionsStagehandGotoOptionsNo—

Returns RemoteStagehandResponse \| null

Upstream docs

reload(options?)

Reload the current page.

Options include:

  • waitUntil: ‘load’ | ‘domcontentloaded’ | ‘networkidle’
  • timeoutMs: Maximum reload time in milliseconds
  • ignoreCache: Whether to bypass the browser cache
1await page.reload();
ParameterTypeRequiredDescription
optionsStagehandReloadOptionsNo—

Returns RemoteStagehandResponse \| null

Upstream docs

goBack(options?)

Navigate to the previous page in history.

Returns null if there is no previous page.

1await page.goBack();
ParameterTypeRequiredDescription
optionsStagehandGotoOptionsNo—

Returns RemoteStagehandResponse \| null

Upstream docs

goForward(options?)

Navigate to the next page in history.

Returns null if there is no next page.

1await page.goForward();
ParameterTypeRequiredDescription
optionsStagehandGotoOptionsNo—

Returns RemoteStagehandResponse \| null

Upstream docs

waitForLoadState(state?, options?)

Wait for the page to reach a specific load state.

States:

  • ‘load’: Wait for the load event
  • ‘domcontentloaded’: Wait for DOMContentLoaded event
  • ‘networkidle’: Wait until no network connections for 500ms
1await page.waitForLoadState("domcontentloaded");
ParameterTypeRequiredDescription
stateStagehandLoadStateNoLoad state to wait for.
options{ timeout?: number }No—

Upstream docs

Page Info

url()

Get the current URL of the page.

This is a synchronous method that returns the current URL.

1const currentUrl = page.url();

Returns string

Upstream docs

title()

Get the title of the page.

1const title = await page.title();

Returns string

Upstream docs

setViewportSize(width, height, options?)

Set the viewport size of the page.

1await page.setViewportSize(1280, 720);
ParameterTypeRequiredDescription
widthnumberYesViewport width in pixels.
heightnumberYesViewport height in pixels.
optionsStagehandViewportOptionsNoAdditional viewport options.

Upstream docs

Actions

click(x, y, options?)

Click at the specified coordinates.

Options include:

  • button: ‘left’ | ‘right’ | ‘middle’ (default: ‘left’)
  • clickCount: Number of clicks (default: 1, use 2 for double-click)
  • returnXpath: If true, returns the XPath of the clicked element
1await page.click(100, 200);
ParameterTypeRequiredDescription
xnumberYesX coordinate to click.
ynumberYesY coordinate to click.
optionsStagehandClickOptionsNo—

Returns string \| void

Upstream docs

hover(x, y, options?)

Hover at the specified coordinates.

If returnXpath is true, returns the XPath of the hovered element.

1await page.hover(300, 150);
ParameterTypeRequiredDescription
xnumberYesX coordinate to hover over.
ynumberYesY coordinate to hover over.
optionsStagehandHoverOptionsNo—

Returns string \| void

Upstream docs

scroll(x, y, deltaX, deltaY)

Scroll at the specified position by the given delta.

Positive deltaY scrolls down, negative scrolls up.

1await page.scroll(400, 300, 0, 200); // Scroll down 200px
ParameterTypeRequiredDescription
xnumberYesX coordinate of scroll origin.
ynumberYesY coordinate of scroll origin.
deltaXnumberYesHorizontal scroll amount in pixels.
deltaYnumberYesVertical scroll amount in pixels.

Upstream docs

dragAndDrop(fromX, fromY, toX, toY, options?)

Drag from one point to another.

If returnXpath is true, returns [fromXpath, toXpath] of the dragged elements.

1await page.dragAndDrop(100, 100, 300, 300);
ParameterTypeRequiredDescription
fromXnumberYesStarting X coordinate.
fromYnumberYesStarting Y coordinate.
toXnumberYesEnding X coordinate.
toYnumberYesEnding Y coordinate.
optionsStagehandDragAndDropOptionsNo—

Returns [string, string] \| void

Upstream docs

type(text, options?)

Type text into the currently focused element.

The delay option adds a pause between keystrokes for realistic typing.

1await page.type("Hello, World!");
ParameterTypeRequiredDescription
textstringYesText to type.
optionsStagehandTypeOptionsNo—

Upstream docs

Queries

locator(selector)

Create a locator for an element using a CSS or XPath selector.

Locators support automatic shadow DOM traversal.

1const button = page.locator("button.submit");
ParameterTypeRequiredDescription
selectorstringYesCSS or XPath selector.

Returns RemoteStagehandLocator

Upstream docs

deepLocator(selector)

Create a deep locator that can traverse iframes and shadow roots.

Deep locators use hop notation to navigate through iframes:

  • Use >>> to hop into an iframe
  • Example: “#outer-frame >>> #inner-frame >>> button”
1const nestedButton = page.deepLocator("button.nested-action");
ParameterTypeRequiredDescription
selectorstringYesSelector with optional hop notation for iframes.

Returns RemoteStagehandLocator

Upstream docs

Waiting

waitForSelector(selector, options?)

Wait for an element matching the selector to appear.

Options include:

  • state: ‘visible’ | ‘hidden’ | ‘attached’ | ‘detached’
  • timeout: Maximum wait time in milliseconds
  • pierceShadow: Whether to pierce shadow DOM (default: true)
1await page.waitForSelector("#submit-btn");
ParameterTypeRequiredDescription
selectorstringYesSelector to wait for.
optionsStagehandWaitForSelectorOptionsNo—

Upstream docs

Screenshots & PDF

screenshot(options?)

Capture a screenshot of the page.

Options include:

  • path: File path to save the screenshot
  • fullPage: Capture the full scrollable page
  • type: ‘png’ | ‘jpeg’
  • quality: JPEG quality (0-100)
  • clip: Specific region to capture
1const buffer = await page.screenshot();
ParameterTypeRequiredDescription
optionsStagehandScreenshotOptionsNo—

Returns Buffer

Upstream docs

snapshot(options?)

Get a snapshot of the page DOM.

Returns a structured representation of the page content.

1const snapshot = await page.snapshot();
ParameterTypeRequiredDescription
optionsStagehandSnapshotOptionsNo—

Returns StagehandSnapshotResult

Upstream docs

Evaluation

evaluate(pageFunction, arg?)

Execute JavaScript code within the page context.

The return value must be JSON-serializable.

1const title = await page.evaluate(() => document.title);
ParameterTypeRequiredDescription
pageFunctionstring | ((arg: Arg) => R | Promise<R>)YesFunction or expression to evaluate in the page context.
argArgNoArgument to pass to the function.

Returns R

Upstream docs

Other

addInitScript(script, arg?)

Add an initialization script that runs before page scripts.

The script runs on every navigation.

1await page.addInitScript(() => { window.injected = true; });
ParameterTypeRequiredDescription
scriptstring | { path?: string; content?: string } | ((arg: Arg) => unknown)YesThe script to inject.
argArgNoArgument to pass to the function.

Upstream docs