> ## Documentation Index
> Fetch the complete documentation index at: https://stagehand-stg-1784.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# observe()

> Complete API reference for the observe() method

<CardGroup cols={1}>
  <Card title="Observe" icon="magnifying-glass" href="/v2/basics/observe">
    See how to use observe() to discover actionable elements and analyze web page structure
  </Card>
</CardGroup>

### Method Signatures

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    // With ObserveOptions
    await page.observe(options: ObserveOptions): Promise<ObserveResult[]>

    // String instruction shorthand
    await page.observe(instruction: string): Promise<ObserveResult[]>
    ```

    **ObserveOptions Interface:**

    ```typescript theme={null}
    interface ObserveOptions {
      instruction?: string;
      modelName?: AvailableModel;
      modelClientOptions?: ClientOptions;
      domSettleTimeoutMs?: number;
      drawOverlay?: boolean;
      iframes?: boolean;
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # With parameters
    await page.observe(
        instruction: str,
        dom_settle_timeout_ms: int = None,
        iframes: bool = None,
        model_name: AvailableModel = None,
        model_client_options: Dict = None
    ) -> List[ObserveResult]
    ```
  </Tab>
</Tabs>

### Parameters

<ParamField path="instruction" type="string" optional>
  Natural language description of elements or actions to discover.
</ParamField>

<ParamField path="modelName" type="AvailableModel" optional>
  Override the default LLM model for this observation.
</ParamField>

<ParamField path="modelClientOptions" type="ClientOptions" optional>
  Model-specific configuration options.
</ParamField>

<ParamField path="domSettleTimeoutMs" type="number" optional>
  Maximum time to wait for DOM to stabilize before analysis.

  **Default:** `30000`
</ParamField>

<ParamField path="drawOverlay" type="boolean" optional>
  Whether to draw visual overlays on discovered elements (debugging).

  **Default:** `false`
</ParamField>

<ParamField path="iframes" type="boolean" optional>
  Set to `true` to search within iframes.

  **Default:** `false`
</ParamField>

### Response

**Returns:** `Promise<ObserveResult[]>`

Array of discovered actionable elements, ordered by relevance.

**ObserveResult Interface:**

```typescript theme={null}
interface ObserveResult {
  selector: string;        // XPath selector to locate element
  description: string;     // Human-readable description
  method?: string;         // Suggested action method
  arguments?: string[];    // Additional action parameters
}
```

<ParamField path="selector" type="string">
  XPath selector that precisely locates the element.
</ParamField>

<ParamField path="description" type="string">
  Human-readable description of the element and its purpose.
</ParamField>

<ParamField path="method" type="string" optional>
  Suggested interaction method: `"click"`, `"fill"`, `"selectOptionFromDropdown"`, `"nextChunk"`, `"scrollTo"`, `"prevChunk"`.
</ParamField>

<ParamField path="arguments" type="string[]" optional>
  Additional parameters for the suggested action.
</ParamField>

### Code Examples

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Basic element discovery
  const buttons = await page.observe("find all clickable buttons");
  const formFields = await page.observe("locate form input fields");

  // Advanced configuration
  const elements = await page.observe({
    instruction: "find important call-to-action buttons",
    modelName: "gpt-4.1-mini",
    domSettleTimeoutMs: 45000,
    drawOverlay: true
  });

  // Working with results
  const [loginButton] = await page.observe("find the login button");
  if (loginButton) {
    console.log("Found:", loginButton.description);
    console.log("Selector:", loginButton.selector);
    await page.act(loginButton); // Execute the action
  }

  // Filter results
  const submitButtons = await page.observe("find all submit buttons");
  const primarySubmit = submitButtons.find(btn => 
    btn.description.toLowerCase().includes('primary')
  );

  // Iframe search
  const iframeElements = await page.observe({
    instruction: "find form fields inside the iframe",
    iframes: true
  });
  ```

  ```python Python theme={null}
  # Basic element discovery
  buttons = await page.observe("find all clickable buttons")
  form_fields = await page.observe("locate the form fields")

  # Advanced configuration  
  elements = await page.observe(
      instruction="find important call-to-action buttons",
      model_name="gpt-4.1-mini",
      dom_settle_timeout_ms=45000
  )

  # Working with results
  login_buttons = await page.observe("find the login button")
  if login_buttons:
      button = login_buttons[0]
      print("Found:", button.description)
      print("Selector:", button.selector)
      await page.act(button)  # Execute the action

  # Filter results
  submit_buttons = await page.observe("find all submit buttons")
  primary_submit = next((
      btn for btn in submit_buttons 
      if 'primary' in btn.description.lower()
  ), None)

  # Iframe search
  iframe_elements = await page.observe(
      instruction="find the form fields inside the iframe",
      iframes=True
  )
  ```
</CodeGroup>

### Integration Patterns

<CodeGroup>
  ```typescript TypeScript theme={null}
  // Observe → Act workflow
  const actions = await page.observe("find checkout elements");
  for (const action of actions) {
    await page.act(action);
    await page.waitForTimeout(1000);
  }

  // Observe → Extract workflow
  const tables = await page.observe("find data tables");
  if (tables.length > 0) {
    const data = await page.extract({
      instruction: "extract the table data",
      selector: tables[0].selector,
      schema: DataSchema
    });
  }

  // Element validation
  const requiredElements = await page.observe("find the login form");
  if (requiredElements.length === 0) {
    throw new Error("Login form not found");
  }
  ```

  ```python Python theme={null}
  # Observe → Act workflow  
  actions = await page.observe("find checkout elements")
  for action in actions:
      await page.act(action)
      await page.wait_for_timeout(1000)

  # Observe → Extract workflow
  tables = await page.observe("find data tables")
  if tables:
      data = await page.extract(
          instruction="extract the table data",
          selector=tables[0].selector,
          schema=DataSchema
      )

  # Element validation
  required_elements = await page.observe("find login form")
  if not required_elements:
      raise Exception("Login form not found")
  ```
</CodeGroup>