---
title: "Page Observe"
method: POST
path: "/sessions/{session_id}/page/observe"
tags: ["sessions", "page"]
---

# Page Observe

`POST /sessions/{session_id}/page/observe`

## Path parameters

- `session_id` string, required

## Query parameters

- `update_metadata` boolean

## Headers

- `x-notte-request-origin` string, nullable
- `x-notte-sdk-version` string, nullable

## Request body

- ObserveRequest
  - `min_nb_actions` integer, nullable — The minimum number of actions to list before stopping. If not provided, the listing will continue until the maximum number of actions is reached.
  - `max_nb_actions` integer — The maximum number of actions to list after which the listing will stop. Used when min_nb_actions is not provided.
  - `instructions` string, nullable — Additional instructions to use for the observation.
  - `perception_type` 'fast' | 'deep', nullable — Whether to run with fast or deep perception

## Response `200`

Successful Response

- Observation
  - `started_at` string, date-time, required
  - `ended_at` string, date-time, required
  - `metadata` SnapshotMetadata, required
    - `title` string, required
    - `url` string, required
    - `viewport` ViewportData, required
      - `scroll_x` integer, required
      - `scroll_y` integer, required
      - `viewport_width` integer, required
      - `viewport_height` integer, required
      - `total_width` integer, required
      - `total_height` integer, required
    - `tabs` TabsData[], required
      - `tab_id` integer, required
      - `title` string, required
      - `url` string, required
    - `timestamp` string, date-time — Timestamp of the snapshot
  - `screenshot` Screenshot, required
    - `raw` string, binary, required
    - `bboxes` BoundingBox[]
      - `x` number, required
      - `y` number, required
      - `width` number, required
      - `height` number, required
      - `scroll_x` number, required
      - `scroll_y` number, required
      - `iframe_offset_x` number
      - `iframe_offset_y` number
      - `viewport_width` number, required
      - `viewport_height` number, required
      - `notte_id` string, nullable
    - `last_action_id` string, nullable
  - `space` ActionSpace, required
    - `description` string, required — Human-readable description of the current web page
    - `interaction_actions` union[], required — List of available interaction actions in the current state
      - union
        - ClickActionOutput
          - `type` 'click'
          - `category` string
          - `description` string
          - `id` string
          - `selector` union
            - string
            - NodeSelectors
              - …
          - `press_enter` boolean, nullable
          - `text_label` string, nullable
          - `timeout` integer — Action timeout in milliseconds
        - FillActionOutput
          - `type` 'fill'
          - `category` string
          - `description` string
          - `id` string
          - `selector` union
            - string
            - NodeSelectors
              - …
          - `press_enter` boolean, nullable
          - `text_label` string, nullable
          - `timeout` integer — Action timeout in milliseconds
          - `value` union, required
            - string
            - string, password
          - `clear_before_fill` boolean
        - MultiFactorFillActionOutput
          - `type` 'multi_factor_fill'
          - `category` string
          - `description` string
          - `id` string
          - `selector` union
            - string
            - NodeSelectors
              - …
          - `press_enter` boolean, nullable
          - `text_label` string, nullable
          - `timeout` integer — Action timeout in milliseconds
          - `value` union, required
            - string
            - string, password
          - `clear_before_fill` boolean
        - FallbackFillActionOutput
          - `type` 'fallback_fill'
          - `category` string
          - `description` string
          - `id` string
          - `selector` union
            - string
            - NodeSelectors
              - …
          - `press_enter` boolean, nullable
          - `text_label` string, nullable
          - `timeout` integer — Action timeout in milliseconds
          - `value` union, required
            - string
            - string, password
          - `clear_before_fill` boolean
        - CheckActionOutput
          - `type` 'check'
          - `category` string
          - `description` string
          - `id` string
          - `selector` union
            - string
            - NodeSelectors
              - …
          - `press_enter` boolean, nullable
          - `text_label` string, nullable
          - `timeout` integer — Action timeout in milliseconds
          - `value` boolean, required
        - SelectDropdownOptionActionOutput
          - `type` 'select_dropdown_option'
          - `category` string
          - `description` string
          - `id` string
          - `selector` union
            - string
            - NodeSelectors
              - …
          - `press_enter` boolean, nullable
          - `text_label` string, nullable
          - `timeout` integer — Action timeout in milliseconds
          - `value` union, required
            - string
            - string, password
        - UploadFileActionOutput
          - `type` 'upload_file'
          - `category` string
          - `description` string
          - `id` string
          - `selector` union
            - string
            - NodeSelectors
              - …
          - `press_enter` boolean, nullable
          - `text_label` string, nullable
          - `timeout` integer — Action timeout in milliseconds
          - `file_path` string, required
        - DownloadFileActionOutput
          - `type` 'download_file'
          - `category` string
          - `description` string
          - `id` string
          - `selector` union
            - string
            - NodeSelectors
              - …
          - `press_enter` boolean, nullable
          - `text_label` string, nullable
          - `timeout` integer — Action timeout in milliseconds
    - `category` 'homepage' | 'search-results' | 'data-feed' | 'item' | 'auth' | 'form' | 'manage-cookies' | 'overlay' | 'payment' | 'captcha' | 'other'
    - `actions` union[], required
      - union
        - FormFillAction
          - `type` 'form_fill'
          - `category` string
          - `description` string
          - `value` object, required
        - GotoAction
          - `type` 'goto'
          - `category` string
          - `description` string
          - `url` string, required
        - GotoNewTabAction
          - `type` 'goto_new_tab'
          - `category` string
          - `description` string
          - `url` string, required
        - CloseTabAction
          - `type` 'close_tab'
          - `category` string
          - `description` string
        - SwitchTabAction
          - `type` 'switch_tab'
          - `category` string
          - `description` string
          - `tab_index` integer, required
        - GoBackAction
          - `type` 'go_back'
          - `category` string
          - `description` string
        - GoForwardAction
          - `type` 'go_forward'
          - `category` string
          - `description` string
        - ReloadAction
          - `type` 'reload'
          - `category` string
          - `description` string
        - WaitAction
          - `type` 'wait'
          - `category` string
          - `description` string
          - `time_ms` integer, required — The amount of time to wait in milliseconds (max 30 seconds)
        - PressKeyAction
          - `type` 'press_key'
          - `category` string
          - `description` string
          - `key` string, required
        - ScrollUpAction
          - `type` 'scroll_up'
          - `category` string
          - `description` string
          - `amount` integer, nullable
        - ScrollDownAction
          - `type` 'scroll_down'
          - `category` string
          - `description` string
          - `amount` integer, nullable
        - CaptchaSolveAction
          - `type` 'captcha_solve'
          - `category` string
          - `description` string
          - `captcha_type` 'recaptcha' | 'hcaptcha' | 'image' | 'text' | 'auth0' | 'cloudflare' | 'datadome' | 'arkose labs' | 'geetest' | 'press&hold' | 'unknown', nullable
        - HelpAction
          - `type` 'help'
          - `category` string
          - `description` string
          - `reason` string, required
        - CompletionAction
          - `type` 'completion'
          - `category` string
          - `description` string
          - `success` boolean, required
          - `answer` string, required
        - ScrapeAction
          - `type` 'scrape'
          - `category` string
          - `description` string
          - `instructions` string, nullable
          - `only_main_content` boolean — Whether to only scrape the main content of the page. If True, navbars, footers, etc. are excluded.
          - `selector` string, nullable — Playwright selector to scope the scrape to. Only content inside this selector will be scraped.
          - `only_images` boolean — Whether to only scrape images from the page. If True, the page content is excluded.
          - `scrape_links` boolean — Whether to scrape links from the page. Links are scraped by default.
          - `scrape_images` boolean — Whether to scrape images from the page.
          - `ignored_tags` string[], nullable — HTML tags to ignore from the page.
          - `response_format` object, nullable — JSON schema dict for structured output. Agent can provide a schema to extract structured data.
        - EmailReadAction
          - `type` 'email_read'
          - `category` string
          - `description` string
          - `limit` integer — Max number of emails to return
          - `timedelta` string, duration, nullable — Return only emails that are not older than `timedelta`
          - `only_unread` boolean — Return only previously unread emails
        - SmsReadAction
          - `type` 'sms_read'
          - `category` string
          - `description` string
          - `limit` integer — Max number of sms to return
          - `timedelta` string, duration, nullable — Return only sms that are not older than `timedelta`
          - `only_unread` boolean — Return only previously unread sms
        - EvaluateJsAction
          - `type` 'evaluate_js'
          - `category` string
          - `description` string
          - `code` string, required — The JavaScript code to evaluate on the page. Use a single expression or an IIFE for multi-statement code.
        - ClickActionOutput
          - `type` 'click'
          - `category` string
          - `description` string
          - `id` string
          - `selector` union
            - string
            - NodeSelectors
              - …
          - `press_enter` boolean, nullable
          - `text_label` string, nullable
          - `timeout` integer — Action timeout in milliseconds
        - FillActionOutput
          - `type` 'fill'
          - `category` string
          - `description` string
          - `id` string
          - `selector` union
            - string
            - NodeSelectors
              - …
          - `press_enter` boolean, nullable
          - `text_label` string, nullable
          - `timeout` integer — Action timeout in milliseconds
          - `value` union, required
            - string
            - string, password
          - `clear_before_fill` boolean
        - MultiFactorFillActionOutput
          - `type` 'multi_factor_fill'
          - `category` string
          - `description` string
          - `id` string
          - `selector` union
            - string
            - NodeSelectors
              - …
          - `press_enter` boolean, nullable
          - `text_label` string, nullable
          - `timeout` integer — Action timeout in milliseconds
          - `value` union, required
            - string
            - string, password
          - `clear_before_fill` boolean
        - FallbackFillActionOutput
          - `type` 'fallback_fill'
          - `category` string
          - `description` string
          - `id` string
          - `selector` union
            - string
            - NodeSelectors
              - …
          - `press_enter` boolean, nullable
          - `text_label` string, nullable
          - `timeout` integer — Action timeout in milliseconds
          - `value` union, required
            - string
            - string, password
          - `clear_before_fill` boolean
        - CheckActionOutput
          - `type` 'check'
          - `category` string
          - `description` string
          - `id` string
          - `selector` union
            - string
            - NodeSelectors
              - …
          - `press_enter` boolean, nullable
          - `text_label` string, nullable
          - `timeout` integer — Action timeout in milliseconds
          - `value` boolean, required
        - SelectDropdownOptionActionOutput
          - `type` 'select_dropdown_option'
          - `category` string
          - `description` string
          - `id` string
          - `selector` union
            - string
            - NodeSelectors
              - …
          - `press_enter` boolean, nullable
          - `text_label` string, nullable
          - `timeout` integer — Action timeout in milliseconds
          - `value` union, required
            - string
            - string, password
        - UploadFileActionOutput
          - `type` 'upload_file'
          - `category` string
          - `description` string
          - `id` string
          - `selector` union
            - string
            - NodeSelectors
              - …
          - `press_enter` boolean, nullable
          - `text_label` string, nullable
          - `timeout` integer — Action timeout in milliseconds
          - `file_path` string, required
        - DownloadFileActionOutput
          - `type` 'download_file'
          - `category` string
          - `description` string
          - `id` string
          - `selector` union
            - string
            - NodeSelectors
              - …
          - `press_enter` boolean, nullable
          - `text_label` string, nullable
          - `timeout` integer — Action timeout in milliseconds
    - `browser_actions` union[], required
      - union
        - FormFillAction
          - `type` 'form_fill'
          - `category` string
          - `description` string
          - `value` object, required
        - GotoAction
          - `type` 'goto'
          - `category` string
          - `description` string
          - `url` string, required
        - GotoNewTabAction
          - `type` 'goto_new_tab'
          - `category` string
          - `description` string
          - `url` string, required
        - CloseTabAction
          - `type` 'close_tab'
          - `category` string
          - `description` string
        - SwitchTabAction
          - `type` 'switch_tab'
          - `category` string
          - `description` string
          - `tab_index` integer, required
        - GoBackAction
          - `type` 'go_back'
          - `category` string
          - `description` string
        - GoForwardAction
          - `type` 'go_forward'
          - `category` string
          - `description` string
        - ReloadAction
          - `type` 'reload'
          - `category` string
          - `description` string
        - WaitAction
          - `type` 'wait'
          - `category` string
          - `description` string
          - `time_ms` integer, required — The amount of time to wait in milliseconds (max 30 seconds)
        - PressKeyAction
          - `type` 'press_key'
          - `category` string
          - `description` string
          - `key` string, required
        - ScrollUpAction
          - `type` 'scroll_up'
          - `category` string
          - `description` string
          - `amount` integer, nullable
        - ScrollDownAction
          - `type` 'scroll_down'
          - `category` string
          - `description` string
          - `amount` integer, nullable
        - CaptchaSolveAction
          - `type` 'captcha_solve'
          - `category` string
          - `description` string
          - `captcha_type` 'recaptcha' | 'hcaptcha' | 'image' | 'text' | 'auth0' | 'cloudflare' | 'datadome' | 'arkose labs' | 'geetest' | 'press&hold' | 'unknown', nullable
        - HelpAction
          - `type` 'help'
          - `category` string
          - `description` string
          - `reason` string, required
        - CompletionAction
          - `type` 'completion'
          - `category` string
          - `description` string
          - `success` boolean, required
          - `answer` string, required
        - ScrapeAction
          - `type` 'scrape'
          - `category` string
          - `description` string
          - `instructions` string, nullable
          - `only_main_content` boolean — Whether to only scrape the main content of the page. If True, navbars, footers, etc. are excluded.
          - `selector` string, nullable — Playwright selector to scope the scrape to. Only content inside this selector will be scraped.
          - `only_images` boolean — Whether to only scrape images from the page. If True, the page content is excluded.
          - `scrape_links` boolean — Whether to scrape links from the page. Links are scraped by default.
          - `scrape_images` boolean — Whether to scrape images from the page.
          - `ignored_tags` string[], nullable — HTML tags to ignore from the page.
          - `response_format` object, nullable — JSON schema dict for structured output. Agent can provide a schema to extract structured data.
        - EmailReadAction
          - `type` 'email_read'
          - `category` string
          - `description` string
          - `limit` integer — Max number of emails to return
          - `timedelta` string, duration, nullable — Return only emails that are not older than `timedelta`
          - `only_unread` boolean — Return only previously unread emails
        - SmsReadAction
          - `type` 'sms_read'
          - `category` string
          - `description` string
          - `limit` integer — Max number of sms to return
          - `timedelta` string, duration, nullable — Return only sms that are not older than `timedelta`
          - `only_unread` boolean — Return only previously unread sms
        - EvaluateJsAction
          - `type` 'evaluate_js'
          - `category` string
          - `description` string
          - `code` string, required — The JavaScript code to evaluate on the page. Use a single expression or an IIFE for multi-statement code.
    - `markdown` string, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/notte/apis/notte-api.md) · [All operations](https://skmtc.net/notte/apis/notte-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/notte/notte-api/versions/8dda4e3d49cc/schema)