Skip to main content
Sessions provide a comprehensive set of browser actions for interacting with web pages. All actions are executed through session.execute().

​
Goto

Navigate to a URL. 
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    session.execute(type="goto", url="https://example.com")
Parameters:
  • url (str): The URL to navigate to
Use for: Opening pages, navigating between pages

​
GotoNewTab

Open a URL in a new browser tab. 
session.execute(type="goto_new_tab", url="https://example.com/products")
Parameters:
  • url (str): The URL to open in a new tab
Use for: Opening multiple pages simultaneously, preserving context

​
SwitchTab

Switch to a different browser tab. 
# Open multiple tabs
session.execute(type="goto", url="https://example.com")
session.execute(type="goto_new_tab", url="https://example.com/products")

# Switch back to first tab
session.execute(type="switch_tab", tab_index=0)
Parameters:
  • tab_index (int): Zero-based index of the tab to switch to
Use for: Managing multiple tabs, comparing content across pages

​
GoBack

Navigate back to the previous page. 
session.execute(type="goto", url="https://example.com")
session.execute(type="goto", url="https://example.com/products")

# Go back to homepage
session.execute(type="go_back")
Use for: Browser back button functionality, returning to previous pages

​
GoForward

Navigate forward in browser history. 
session.execute(type="go_back")
# Now go forward again
session.execute(type="go_forward")
Use for: Browser forward button functionality

​
Reload

Reload the current page. 
session.execute(type="reload")
Use for: Refreshing page content, retrying after errors

​
Interaction Actions

​
Click

Click on an element. 
# Click by CSS selector
session.execute(type="click", selector="button#submit")

# Click by ID
session.execute(type="click", id="submit-btn")

# Click by text content
session.execute(type="click", text="Submit")
Parameters:
  • selector (str): CSS selector for the element
  • id (str): Element ID
  • text (str): Exact text content
  • aria_label (str): ARIA label attribute
  • placeholder (str): Placeholder text
  • title (str): Title attribute
Use for: Clicking buttons, links, checkboxes, any clickable element

​
Fill

Fill a text input or textarea. 
# Fill by selector
session.execute(
    type="fill",
    selector="input[name='email']",
    value="user@example.com"
)

# Fill by ID
session.execute(type="fill", id="email-input", value="user@example.com")

# Fill by placeholder
session.execute(
    type="fill",
    placeholder="Enter your email",
    value="user@example.com"
)
Parameters:
  • selector (str): CSS selector for the input
  • id (str): Element ID
  • placeholder (str): Placeholder text
  • aria_label (str): ARIA label
  • value (str): The text to fill
Use for: Filling forms, search boxes, text inputs

​
Check

Check or uncheck a checkbox. 
# Check a checkbox
session.execute(
    type="check",
    selector="input[type='checkbox']#terms",
    checked=True
)

# Uncheck a checkbox
session.execute(
    type="check",
    selector="input[type='checkbox']#newsletter",
    checked=False
)
Parameters:
  • selector (str): CSS selector for the checkbox
  • id (str): Element ID
  • checked (bool): True to check, False to uncheck
Use for: Toggling checkboxes, accepting terms, selecting options

​
SelectDropdownOption

Select an option from a dropdown. 
# Select by visible text
session.execute(
    type="select_dropdown_option",
    selector="select#country",
    option_text="United States"
)

# Select by value
session.execute(
    type="select_dropdown_option",
    selector="select#country",
    option_value="us"
)
Parameters:
  • selector (str): CSS selector for the select element
  • option_text (str): Visible text of the option
  • option_value (str): Value attribute of the option
Use for: Selecting from dropdowns, choosing options

​
PressKey

Press a keyboard key. 
# Press Enter
session.execute(type="press_key", key="Enter")

# Press Escape
session.execute(type="press_key", key="Escape")

# Press Tab
session.execute(type="press_key", key="Tab")
Parameters:
  • key (str): Key name (e.g., “Enter”, “Escape”, “Tab”, “ArrowDown”)
Use for: Keyboard navigation, submitting forms, triggering shortcuts Common keys: Enter, Escape, Tab, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Backspace, Delete

​
Scrolling Actions

​
ScrollUp

Scroll up on the page. 
session.execute(type="scroll_up")
Use for: Scrolling to top of page, revealing content above

​
ScrollDown

Scroll down on the page. 
session.execute(type="scroll_down")
Use for: Loading lazy content, revealing content below, pagination

​
File Actions

​
UploadFile

Upload a file to a file input. 
# Upload from local file
session.execute(
    type="upload_file",
    selector="input[type='file']",
    file_path="/path/to/document.pdf"
)

# Upload with ID
session.execute(type="upload_file", id="file-upload", file_path="/path/to/image.jpg")
Parameters:
  • selector (str): CSS selector for the file input
  • id (str): Element ID
  • file_path (str): Path to the file to upload
Use for: Uploading documents, images, any file input

​
DownloadFile

Download a file from a link. 
session.execute(type="download_file", selector="a.download-link")

# Access downloaded file
downloaded_files = session.storage.list_downloaded_files()
for file in downloaded_files:
    content = session.storage.download(file.file_id)
Parameters:
  • selector (str): CSS selector for the download link
  • id (str): Element ID
Use for: Downloading files, reports, documents

​
Wait Action

​
Wait

Pause execution for a specified duration. 
# Wait 2 seconds
session.execute(type="wait", duration=2000)

# Wait 5 seconds for page to load
session.execute(type="wait", duration=5000)
Parameters:
  • duration (int): Time to wait in milliseconds
Use for: Waiting for page loads, animations, dynamic content
Tip: Use sparingly. Notte automatically waits for page loads and element visibility. Only use Wait for specific timing requirements.

​
Data Extraction

​
Scrape

Extract data from the current page. 
# Get page markdown
markdown = session.scrape()

# Extract with instructions
data = session.scrape(
    instructions="Extract all product names and prices"
)

# Structured extraction
from pydantic import BaseModel

class Product(BaseModel):
    name: str
    price: float

products = session.scrape(
    response_format=list[Product],
    instructions="Extract all products"
)
Parameters:
  • instructions (str): Natural language extraction instructions
  • response_format (type[BaseModel]): Pydantic model for structured output
  • only_main_content (bool): Extract only main content, ignore headers/footers
Use for: Data extraction, web scraping, content analysis See Scraping for detailed documentation.

​
Communication Actions

​
SmsRead

Read SMS messages from a persona’s phone number. 
# Create persona with phone number
persona = client.Persona()
number = persona.create_number(country="US")

# Use in session
with client.Session() as session:
    # Trigger SMS (e.g., 2FA code)
    session.execute(
        type="fill",
        selector="input[name='phone']",
        value=number.phone_number
    )
    session.execute(type="click", selector="button.send-code")

    # Read SMS
    messages = session.execute(type="sms_read", persona_id=persona.persona_id)

    # Extract verification code
    code = extract_code(messages)
Parameters:
  • persona_id (str): Persona ID with phone number
Use for: Reading 2FA codes, SMS verification, phone-based authentication See Personas for details.

​
EmailRead

Read emails from a persona’s email address. 
# Create persona with email
persona = client.Persona()
emails = persona.emails()

# Use in session
with client.Session() as session:
    # Trigger email (e.g., verification email)
    session.execute(
        type="fill",
        selector="input[name='email']",
        value=emails[0]
    )
    session.execute(type="click", selector="button.send-verification")

    # Read email
    messages = session.execute(type="email_read", persona_id=persona.persona_id)

    # Extract verification link
    link = extract_link(messages)
Parameters:
  • persona_id (str): Persona ID with email address
Use for: Reading verification emails, email-based authentication See Personas for details.

​
Action Patterns

​
Chaining Actions

Execute multiple actions in sequence:
action_chaining.py
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    # Navigation
    session.execute(type="goto", url="https://example.com/login")

    # Form filling
    session.execute(
        type="fill",
        selector="input[name='email']",
        value="user@example.com"
    )
    session.execute(
        type="fill",
        selector="input[name='password']",
        value="password123"
    )

    # Submission
    session.execute(type="click", selector="button[type='submit']")

    # Wait for redirect
    session.execute(type="wait", duration=2000)

    # Verify success
    content = session.scrape()
    print(content)

​
Error Handling

Handle action failures:
error_handling.py
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    session.execute(type="goto", url="https://example.com")

    # Don't raise on failure
    result = session.execute(
        type="click",
        selector="button.maybe-exists",
        raise_on_failure=False
    )

    if result.success:
        print("Button clicked successfully")
        session.execute(type="click", selector="button.next")
    else:
        print(f"Click failed: {result.message}")
        # Try alternative approach
        session.execute(type="click", selector="button.alternative")

​
Conditional Actions

Execute actions based on conditions: 
# Check if element exists
result = session.execute(
    type="click",
    selector="button.optional",
    raise_on_failure=False
)

if result.success:
    # Element was there and clicked
    session.execute(type="click", selector="button.next")
else:
    # Element wasn't there, skip
    print("Optional button not found, continuing...")

​
Selector Strategies

​
CSS Selectors

Most flexible and commonly used: 
# By ID
session.execute(type="click", selector="#submit-button")

# By class
session.execute(type="click", selector=".btn-primary")

# By attribute
session.execute(type="click", selector="button[type='submit']")

# By combination
session.execute(type="click", selector="form#login button.submit")

# By nth-child
session.execute(type="click", selector="ul li:nth-child(2)")

​
Direct Attributes

Use direct attribute parameters when available: 
# By ID (cleaner)
session.execute(type="click", id="submit-button")

# By text content
session.execute(type="click", text="Submit")

# By placeholder
session.execute(type="fill", placeholder="Enter email", value="user@example.com")

# By ARIA label
session.execute(type="click", aria_label="Close dialog")

​
Best Practices

Prefer stable selectors: 
# Good - uses ID (stable)
session.execute(type="click", id="submit-btn")

# Good - uses data attribute
session.execute(type="click", selector="button[data-testid='submit']")

# Avoid - fragile position-based
session.execute(type="click", selector="div > div > button:nth-child(3)")
Use specific selectors: 
# Good - specific
session.execute(type="fill", selector="form#login input[name='email']", value="user@example.com")

# Less specific - might match wrong element
session.execute(type="fill", selector="input", value="user@example.com")

​
Common Workflows

​
Form Submission

form_submission.py
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    session.execute(type="goto", url="https://example.com/contact")
    session.execute(type="fill", id="name", value="John Doe")
    session.execute(type="fill", id="email", value="john@example.com")
    session.execute(type="fill", id="message", value="Hello!")
    session.execute(type="click", selector="button[type='submit']")

​
Search and Extract

search_extract.py
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    session.execute(type="goto", url="https://example.com")
    session.execute(
        type="fill",
        placeholder="Search",
        value="laptop"
    )
    session.execute(type="press_key", key="Enter")
    session.execute(type="wait", duration=2000)

    results = session.scrape(
        instructions="Extract search results"
    )
    print(results)

​
Multi-Tab Workflow

multi_tab.py
from notte_sdk import NotteClient

client = NotteClient()

def process_data(data):
    print(f"Processed: {data[:100]}...")

with client.Session() as session:
    # Open multiple tabs
    session.execute(type="goto", url="https://site1.com")
    session.execute(type="goto_new_tab", url="https://site2.com")
    session.execute(type="goto_new_tab", url="https://site3.com")

    # Extract from each tab
    for tab_index in range(3):
        session.execute(type="switch_tab", tab_index=tab_index)
        data = session.scrape()
        process_data(data)

​
File Upload and Download

file_upload_download.py
from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    session.execute(type="goto", url="https://example.com/upload")

    # Upload file
    session.execute(
        type="upload_file",
        selector="input[type='file']",
        file_path="/path/to/document.pdf"
    )
    session.execute(type="click", selector="button.submit")

    # Wait for processing
    session.execute(type="wait", duration=3000)

    # Download result
    session.execute(type="download_file", selector="a.download")

    # Access downloaded files
    downloaded_files = session.storage.list_downloaded_files()
    for file in downloaded_files:
        print(f"Downloaded: {file.file_id}")

​
Next Steps

Session Configuration

Configure session behavior

Session Lifecycle

Manage session states

SDK Actions Reference

Detailed API documentation

Agent Mode

Let AI handle actions automatically