> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://platform.bctrl.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://platform.bctrl.ai/_mcp/server.

# Observe

> Find actionable elements and possible browser actions with Stagehand.

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

```ts
const result = await bctrl.tools.call("stagehand.observe", {
  pageId,
  instruction: "Find the primary button that continues checkout.",
}, { runtimeId: runtime.id });

for (const action of result.actions) {
  console.log(action.description, action.selector);
}
```

`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

| Parameter     | Type      | Required | Description                                                  |
| ------------- | --------- | -------- | ------------------------------------------------------------ |
| `instruction` | `string`  | Yes      | What to find on the page, from 1 to 20,000 characters.       |
| `pageId`      | `PageId`  | No       | Page to inspect. Uses the active page when omitted.          |
| `timeoutMs`   | `integer` | No       | Maximum observation time in milliseconds. Maximum: `120000`. |

## Response

| Field         | Type                | Always present | Description                                       |
| ------------- | ------------------- | -------------- | ------------------------------------------------- |
| `actions`     | `StagehandAction[]` | Yes            | Actionable elements and possible browser actions. |
| `cacheStatus` | `"HIT" \| "MISS"`   | No             | Whether a cached result was used.                 |

Each action contains:

| Field         | Type       | Always present | Description                                |
| ------------- | ---------- | -------------- | ------------------------------------------ |
| `selector`    | `string`   | Yes            | Element selector suggested for the action. |
| `description` | `string`   | Yes            | Human-readable action description.         |
| `method`      | `string`   | No             | Browser method associated with the action. |
| `arguments`   | `string[]` | No             | Arguments associated with the method.      |

## Run asynchronously

```ts
const call = await bctrl.tools.start("stagehand.observe", {
  pageId,
  instruction: "Find every field required to complete this form.",
}, { runtimeId: runtime.id });

const result = await bctrl.toolCalls.result(call.id, {
  waitSeconds: 120,
});
```

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

## Next

* [Stagehand act](/sdk/tools/stagehand/stagehand-act) — perform an action
* [Stagehand extract](/sdk/tools/stagehand/stagehand-extract) — extract structured data
* [Browser pages](/sdk/tools/browser/browser-pages-list) — list and select pages