Observe

Ask Stagehand what actions are available on an active browser page. Use the result to inspect the page before choosing an action, or pass the instruction to your own decision-making code.

Observe a page

1
const result = await bctrl.tools.call("stagehand.observe", {
2
  pageId,
3
  instruction: "Find the primary button that continues checkout.",
4
}, { runtimeId: runtime.id });
5
6
for (const action of result.actions) {
7
  console.log(action.description, action.selector);
8
}

pageId is optional. If omitted, Stagehand observes the Runtime’s active page. instruction must be between 1 and 20,000 characters, and timeoutMs can be up to 120000 milliseconds.

Request parameters

Response

Each action contains:

Run asynchronously

1
const call = await bctrl.tools.start("stagehand.observe", {
2
  pageId,
3
  instruction: "Find every field required to complete this form.",
4
}, { runtimeId: runtime.id });
5
6
const result = await bctrl.toolCalls.result(call.id, {
7
  waitSeconds: 120,
8
});

Use bctrl.toolCalls.get(call.id) to inspect progress or bctrl.toolCalls.cancel(call.id) to cancel an active call.

Next

• Stagehand act — perform an action
• Stagehand extract — extract structured data
• Browser pages — list and select pages