---
title: "Execute Session File"
method: POST
path: "/sessions/{session_id}/page/execute/file"
tags: ["sessions", "files", "page"]
---

# Execute Session File

`POST /sessions/{session_id}/page/execute/file`

## Request

- Base URL: `https://api.notte.cc` (the document declares no server; this is the origin it was published from)
- URL: `https://api.notte.cc/sessions/{session_id}/page/execute/file`
- Auth: OAuth 2
  - Password
  - Token URL: `token`

## 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

- FileExecutionRequest
  - `action` union, required
    - UploadFileActionInput
      - `type` 'upload_file'
      - `category` string
      - `description` string
      - `id` string
      - `selector` union
        - string
        - NodeSelectors
          - `css_selector` string, required
          - `xpath_selector` string, required
          - `in_iframe` boolean, required
          - `in_shadow_root` boolean, required
          - `notte_selector` string, nullable
          - `iframe_parent_css_selectors` string[], required
          - `playwright_selector` string, nullable
          - `python_selector` string, nullable
      - `press_enter` boolean, nullable
      - `text_label` string, nullable
      - `accessible_name` string, nullable
      - `param` ActionParameter
        - `name` string, required
        - `type` string, required
        - `default` string, nullable
        - `values` string[]
      - `timeout` integer: Action timeout in milliseconds
      - `file_path` string, required
    - DownloadFileActionInput
      - `type` 'download_file'
      - `category` string
      - `description` string
      - `id` string
      - `selector` union
        - string
        - NodeSelectors
          - `css_selector` string, required
          - `xpath_selector` string, required
          - `in_iframe` boolean, required
          - `in_shadow_root` boolean, required
          - `notte_selector` string, nullable
          - `iframe_parent_css_selectors` string[], required
          - `playwright_selector` string, nullable
          - `python_selector` string, nullable
      - `press_enter` boolean, nullable
      - `text_label` string, nullable
      - `accessible_name` string, nullable
      - `param` ActionParameter
        - `name` string, required
        - `type` string, required
        - `default` string, nullable
        - `values` string[]
      - `timeout` integer: Action timeout in milliseconds
  - `target_id` string, required
  - `record` boolean

## Response `200`

Successful Response

- ApiExecutionResponse
  - `started_at` string, date-time, required
  - `ended_at` string, date-time, required
  - `action` union, required
    - FormFillAction
      - `type` 'form_fill'
      - `category` string
      - `description` string
      - `value` object, required
    - GotoAction
      - `type` 'goto'
      - `category` string
      - `description` string
      - `url` string, required
      - `wait_until` 'commit' | 'domcontentloaded' | 'load' | 'networkidle', nullable
    - 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
    - WaitActionOutput
      - `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
      - `selector` string, nullable: Optional selector for the scroll container, including iframe paths.
    - ScrollDownAction
      - `type` 'scroll_down'
      - `category` string
      - `description` string
      - `amount` integer, nullable
      - `selector` string, nullable: Optional selector for the scroll container, including iframe paths.
    - 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.
      - `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
    - EmailVerificationReadAction
      - `type` 'email_verification_read'
      - `category` string
      - `description` string
      - `mailbox_id` string, required: Workspace mailbox connection to read the verification email from
      - `sender_domain` string, required: Sender domain to search, such as example.com
      - `max_age_seconds` integer: Maximum age of the verification email in seconds
    - 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
          - `css_selector` string, required
          - `xpath_selector` string, required
          - `in_iframe` boolean, required
          - `in_shadow_root` boolean, required
          - `notte_selector` string, nullable
          - `iframe_parent_css_selectors` string[], required
          - `playwright_selector` string, nullable
          - `python_selector` string, nullable
      - `press_enter` boolean, nullable
      - `text_label` string, nullable
      - `accessible_name` string, nullable
      - `timeout` integer: Action timeout in milliseconds
    - FillActionOutput
      - `type` 'fill'
      - `category` string
      - `description` string
      - `id` string
      - `selector` union
        - string
        - NodeSelectors
          - `css_selector` string, required
          - `xpath_selector` string, required
          - `in_iframe` boolean, required
          - `in_shadow_root` boolean, required
          - `notte_selector` string, nullable
          - `iframe_parent_css_selectors` string[], required
          - `playwright_selector` string, nullable
          - `python_selector` string, nullable
      - `press_enter` boolean, nullable
      - `text_label` string, nullable
      - `accessible_name` 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
          - `css_selector` string, required
          - `xpath_selector` string, required
          - `in_iframe` boolean, required
          - `in_shadow_root` boolean, required
          - `notte_selector` string, nullable
          - `iframe_parent_css_selectors` string[], required
          - `playwright_selector` string, nullable
          - `python_selector` string, nullable
      - `press_enter` boolean, nullable
      - `text_label` string, nullable
      - `accessible_name` 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
          - `css_selector` string, required
          - `xpath_selector` string, required
          - `in_iframe` boolean, required
          - `in_shadow_root` boolean, required
          - `notte_selector` string, nullable
          - `iframe_parent_css_selectors` string[], required
          - `playwright_selector` string, nullable
          - `python_selector` string, nullable
      - `press_enter` boolean, nullable
      - `text_label` string, nullable
      - `accessible_name` 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
          - `css_selector` string, required
          - `xpath_selector` string, required
          - `in_iframe` boolean, required
          - `in_shadow_root` boolean, required
          - `notte_selector` string, nullable
          - `iframe_parent_css_selectors` string[], required
          - `playwright_selector` string, nullable
          - `python_selector` string, nullable
      - `press_enter` boolean, nullable
      - `text_label` string, nullable
      - `accessible_name` 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
          - `css_selector` string, required
          - `xpath_selector` string, required
          - `in_iframe` boolean, required
          - `in_shadow_root` boolean, required
          - `notte_selector` string, nullable
          - `iframe_parent_css_selectors` string[], required
          - `playwright_selector` string, nullable
          - `python_selector` string, nullable
      - `press_enter` boolean, nullable
      - `text_label` string, nullable
      - `accessible_name` 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
          - `css_selector` string, required
          - `xpath_selector` string, required
          - `in_iframe` boolean, required
          - `in_shadow_root` boolean, required
          - `notte_selector` string, nullable
          - `iframe_parent_css_selectors` string[], required
          - `playwright_selector` string, nullable
          - `python_selector` string, nullable
      - `press_enter` boolean, nullable
      - `text_label` string, nullable
      - `accessible_name` 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
          - `css_selector` string, required
          - `xpath_selector` string, required
          - `in_iframe` boolean, required
          - `in_shadow_root` boolean, required
          - `notte_selector` string, nullable
          - `iframe_parent_css_selectors` string[], required
          - `playwright_selector` string, nullable
          - `python_selector` string, nullable
      - `press_enter` boolean, nullable
      - `text_label` string, nullable
      - `accessible_name` string, nullable
      - `timeout` integer: Action timeout in milliseconds
  - `success` boolean, required
  - `message` string, required
  - `data` DataSpace
    - `markdown` string, required: Markdown representation of the extracted data
    - `structured` StructuredDataBaseModel
      - `success` boolean: Whether the data was extracted successfully
      - `error` string, nullable: Error message if the data was not extracted successfully
      - `data` union: Structured data extracted from the page in JSON format
        - BaseModel
        - unknown
  - `exception` string, nullable
  - `exception_detail` SerializedError
    - `error_type` string, required
    - `dev_message` string, required
    - `user_message` string, required
    - `agent_message` string, required
    - `should_retry_later` boolean
    - `should_notify_team` boolean
  - `captcha` CaptchaStatus
    - `captcha_id` string, required
    - `page_id` string, required
    - `generation` integer, required
    - `state` 'solving' | 'solved' | 'failed' | 'cancelled', required
    - `retry_after_ms` integer
    - `message` string
    - `cancel_reason` 'navigation', nullable
  - `action_executed` boolean, nullable
  - `code` string, nullable

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-22** `4d05dac78797`: 2 warning, 11 info
  - removed the optional property `action/oneOf[subschema #16: ScrapeAction]/only_images` from the response with the `200` status
  - removed the optional property `data/anyOf[subschema #1: DataSpace]/images` from the response with the `200` status
  - added the new optional request property `action/oneOf[subschema #1: UploadFileAction]/accessible_name`
  - added the new optional request property `action/oneOf[subschema #2: DownloadFileAction]/accessible_name`
  - …9 more
- **2026-10-19** `d52cb342f7dd`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/notte/apis/notte-api/changes/sessions/:session_id/page/execute/file/post.md)

---

[API](https://skmtc.dev/notte/apis/notte-api.md) - [All operations](https://skmtc.dev/notte/apis/notte-api/llms.txt) - [OpenAPI document](https://skmtc.dev/notte/apis/notte-api/revisions/d56fcbf39bc9?raw)