Fetch

AI agent instructions

Read the Notte skill and follow its setup instructions when setting up Notte or building browser automation. This is the shared source for CLI setup, authentication, and the browser-to-code workflow.

Fetch extracts web page content as markdown or structured data using LLM-powered extraction. In the SDK this is scrape. In the console it is Fetch.

Quick Start

Extract structured data from a page:

from notte_sdk import NotteClient
from pydantic import BaseModel


class HackerNewsPost(BaseModel):
    title: str
    url: str
    points: int
    author: str


class HackerNewsFeed(BaseModel):
    posts: list[HackerNewsPost]


client = NotteClient()

result = client.scrape(
    url="https://news.ycombinator.com",
    response_format=HackerNewsFeed,
    instructions="Extract the top 5 posts from the front page",
)

for i, post in enumerate(result.posts, 1):
    print(f"{i}. {post.points} - {post.title}")

import { z } from 'zod';
import { NotteClient } from 'notte-sdk';

const HackerNewsPost = z.object({
  title: z.string(),
  url: z.string(),
  points: z.number(),
  author: z.string(),
});

const HackerNewsFeed = z.object({
  posts: z.array(HackerNewsPost),
});

const notte = new NotteClient({
  apiKey: process.env.NOTTE_API_KEY,
});

const result = await notte.scrape('https://news.ycombinator.com', {
  instructions: 'Extract the top 5 posts from the front page',
  response_format: HackerNewsFeed,
});

result.posts.forEach((post, index) => {
  console.log(`${index + 1}. ${post.points} - ${post.title}`);
});

Scraping Methods

Notte provides two ways to scrape:

Method	Use Case
`client.scrape(url)`	Quick, one-off scrapes
`session.scrape()`	Scraping after navigation or authentication

Quick Scrape

For simple scraping without session management:

from notte_sdk import NotteClient

client = NotteClient()

# Returns markdown content
markdown = client.scrape("https://example.com")

import { NotteClient } from 'notte-sdk';

const client = new NotteClient();

// Returns markdown content
const markdown = await client.scrape('https://example.com');

Session-Based Scrape

For scraping after authentication or navigation:

from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    # Navigate and authenticate
    session.execute(type="goto", url="https://example.com/login")
    session.execute(type="fill", selector="input[name='email']", value="user@example.com")
    session.execute(type="fill", selector="input[name='password']", value="password")
    session.execute(type="click", selector="button[type='submit']")

    # Navigate to protected page
    session.execute(type="goto", url="https://example.com/dashboard")

    # Scrape the page
    content = session.scrape()

import { NotteClient } from 'notte-sdk';

const client = new NotteClient({
  apiKey: process.env.NOTTE_API_KEY,
});

await client.Session().use(async (session) => {
  // Navigate and authenticate
  await session.execute({ type: 'goto', url: 'https://example.com/login' });
  await session.execute({ type: 'fill', selector: "input[name='email']", value: 'user@example.com' });
  await session.execute({ type: 'fill', selector: "input[name='password']", value: 'password' });
  await session.execute({ type: 'click', selector: "button[type='submit']" });

  // Navigate to protected page
  await session.execute({ type: 'goto', url: 'https://example.com/dashboard' });

  // Scrape the page
  const content = await session.scrape();
});

Structured Extraction

Extract data into typed Python objects using Pydantic models. The extraction is powered by an LLM that understands the page content and extracts the specified fields.

Using Pydantic Models

Define a schema and extract matching data:

from notte_sdk import NotteClient
from pydantic import BaseModel


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


client = NotteClient()
product = client.scrape(
    "https://example.com/product", response_format=Product, instructions="Extract the product details"
)

print(f"Name: {product.name}, Price: {product.price}")

import { z } from 'zod';
import { NotteClient } from 'notte-sdk';

const Product = z.object({
  name: z.string(),
  price: z.number(),
  description: z.string(),
});

const client = new NotteClient({
  apiKey: process.env.NOTTE_API_KEY,
});

const product = await client.scrape('https://example.com/product', {
  response_format: Product,
  instructions: 'Extract the product details',
});

console.log(`Name: ${product.name}, Price: ${product.price}`);

Using Instructions Only

For flexible extraction without a strict schema:

from notte_sdk import NotteClient

client = NotteClient()
result = client.scrape(
    "https://example.com/article", instructions="Extract the article title, author, and publication date"
)

print(result)

import { NotteClient } from 'notte-sdk';

const client = new NotteClient({
  apiKey: process.env.NOTTE_API_KEY,
});

const result = await client.scrape('https://example.com/article', {
  instructions: 'Extract the article title, author, and publication date',
});

console.log(result);

Extracting Lists

Extract multiple items from a page:

from notte_sdk import NotteClient
from pydantic import BaseModel


class Article(BaseModel):
    title: str
    url: str
    summary: str


class ArticleList(BaseModel):
    articles: list[Article]


client = NotteClient()
articles = client.scrape(
    "https://news.example.com", response_format=ArticleList, instructions="Extract all articles from the homepage"
)

for article in articles.articles:
    print(f"{article.title}: {article.url}")

import { z } from 'zod';
import { NotteClient } from 'notte-sdk';

const Article = z.object({
  title: z.string(),
  url: z.string(),
  summary: z.string(),
});

const ArticleList = z.object({
  articles: z.array(Article),
});

const client = new NotteClient({
  apiKey: process.env.NOTTE_API_KEY,
});

const articles = await client.scrape('https://news.example.com', {
  response_format: ArticleList,
  instructions: 'Extract all articles from the homepage',
});

for (const article of articles.articles) {
  console.log(`${article.title}: ${article.url}`);
}

Nested Structures

Handle complex, nested data:

from notte_sdk import NotteClient
from pydantic import BaseModel


class Address(BaseModel):
    street: str
    city: str
    country: str


class Company(BaseModel):
    name: str
    description: str
    address: Address
    employee_count: int | None


client = NotteClient()
company = client.scrape(
    "https://example.com/about", response_format=Company, instructions="Extract company information including address"
)

print(company.address.city)

import { z } from 'zod';
import { NotteClient } from 'notte-sdk';

const Address = z.object({
  street: z.string(),
  city: z.string(),
  country: z.string(),
});

const Company = z.object({
  name: z.string(),
  description: z.string(),
  address: Address,
  employee_count: z.number().nullable(),
});

const client = new NotteClient({
  apiKey: process.env.NOTTE_API_KEY,
});

const company = await client.scrape('https://example.com/about', {
  response_format: Company,
  instructions: 'Extract company information including address',
});

console.log(company.address.city);

Configuration Options

Content Filtering

Control what content gets extracted:

# Only main content (excludes navbars, footers, sidebars)
markdown = client.scrape(url, only_main_content=True)

# Include all page content (default)
markdown = client.scrape(url, only_main_content=False)

// Only main content (excludes navbars, footers, sidebars)
let markdown = await client.scrape(url, { only_main_content: true });

// Include all page content (default)
markdown = await client.scrape(url, { only_main_content: false });

Links

Control link extraction:

# Include links (default)
markdown = client.scrape(url, scrape_links=True)

# Exclude links
markdown = client.scrape(url, scrape_links=False)

// Include links (default)
let markdown = await client.scrape(url, { scrape_links: true });

// Exclude links
markdown = await client.scrape(url, { scrape_links: false });

Scoped Scraping

Scrape only a specific section of the page:

from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    # Scrape content within a specific selector
    content = session.scrape(selector="article.main-content")

    # Scrape a specific container
    content = session.scrape(selector="#product-details")

import { NotteClient } from 'notte-sdk';

const client = new NotteClient({
  apiKey: process.env.NOTTE_API_KEY,
});

await client.Session().use(async (session) => {
  // Scrape content within a specific selector
  const articleContent = await session.scrape({
    selector: 'article.main-content',
  });

  // Scrape a specific container
  const productContent = await session.scrape({
    selector: '#product-details',
  });
});

Link Placeholders

Reduce output size by using placeholders:

# Use placeholders for links and images
markdown = client.scrape(url, use_link_placeholders=True)

// Use placeholders for links and images
const markdown = await client.scrape(url, {
  use_link_placeholders: true,
});

Extraction Model

When you pass instructions or response_format, the extraction runs on the platform’s default model. Set model to use a different one, for example client.scrape(url, instructions="...", model="anthropic/claude-sonnet-4-5-20250929").

Return Types

The scrape method returns different types based on parameters:

Parameters	Return Type
None	`str` (markdown)
`instructions`	`dict` with extracted data
`response_format`	An instance of your model

Pass raise_on_failure=False to get a StructuredData wrapper with success, error, and data fields instead.

Structured Response

When using structured extraction, the extracted data is returned directly:

from notte_sdk import NotteClient
from pydantic import BaseModel


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


client = NotteClient()
url = "https://example.com/product"
product = client.scrape(url, response_format=Product)

# Access the extracted data
print(f"Name: {product.name}, Price: {product.price}")

import { z } from 'zod';
import { NotteClient } from 'notte-sdk';

const Product = z.object({
  name: z.string(),
  price: z.number(),
});

const client = new NotteClient({
  apiKey: process.env.NOTTE_API_KEY,
});

const url = 'https://example.com/product';
const product = await client.scrape(url, {
  response_format: Product,
});

// Access the extracted data
console.log(`Name: ${product.name}, Price: ${product.price}`);

Use Cases

Data Collection

Collect product information:

from notte_sdk import NotteClient
from pydantic import BaseModel


class ProductInfo(BaseModel):
    name: str
    price: float
    rating: float | None
    reviews_count: int | None


client = NotteClient()

urls = [
    "https://store.example.com/product/1",
    "https://store.example.com/product/2",
]

products: list[ProductInfo] = []
for url in urls:
    data = client.scrape(url, response_format=ProductInfo)
    products.append(data)

import { z } from 'zod';
import { NotteClient } from 'notte-sdk';

const ProductInfo = z.object({
  name: z.string(),
  price: z.number(),
  rating: z.number().nullable(),
  reviews_count: z.number().nullable(),
});

const client = new NotteClient({
  apiKey: process.env.NOTTE_API_KEY,
});

const urls = [
  'https://store.example.com/product/1',
  'https://store.example.com/product/2',
];

const products = [];
for (const url of urls) {
  const data = await client.scrape(url, {
    response_format: ProductInfo,
  });
  products.push(data);
}

Content Monitoring

Track content changes:

from notte_sdk import NotteClient

client = NotteClient()

# Get current content
content = client.scrape("https://example.com/pricing", instructions="Extract all pricing tiers and their features")

# Compare with previous version
# ...

import { NotteClient } from 'notte-sdk';

const client = new NotteClient({
  apiKey: process.env.NOTTE_API_KEY,
});

// Get current content
const content = await client.scrape('https://example.com/pricing', {
  instructions: 'Extract all pricing tiers and their features',
});

// Compare with previous version
// ...

Research and Analysis

Extract structured research data:

from notte_sdk import NotteClient
from pydantic import BaseModel


class ResearchPaper(BaseModel):
    title: str
    authors: list[str]
    abstract: str
    publication_date: str | None
    citations: int | None


client = NotteClient()
result = client.scrape("https://papers.example.com/paper/123", response_format=ResearchPaper)

import { z } from 'zod';
import { NotteClient } from 'notte-sdk';

const ResearchPaper = z.object({
  title: z.string(),
  authors: z.array(z.string()),
  abstract: z.string(),
  publication_date: z.string().nullable(),
  citations: z.number().nullable(),
});

const client = new NotteClient({
  apiKey: process.env.NOTTE_API_KEY,
});

const result = await client.scrape('https://papers.example.com/paper/123', {
  response_format: ResearchPaper,
});

Best Practices

1. Use Specific Instructions

Clear instructions improve extraction accuracy:

# Good
instructions = "Extract the product name, price in USD, and availability status"

# Vague
instructions = "Get product info"

// Good
const instructions = 'Extract the product name, price in USD, and availability status';

// Vague
const vagueInstructions = 'Get product info';

2. Define Precise Schemas

Match your schema to the actual page content:

from pydantic import BaseModel


# Good - matches page structure
class GoodProduct(BaseModel):
    name: str
    price: float
    in_stock: bool


# Bad - fields that may not exist
class BadProduct(BaseModel):
    name: str
    price: float
    manufacturer: str  # Page might not have this
    warranty: str  # Page might not have this

import { z } from 'zod';

// Good - matches page structure
const GoodProduct = z.object({
  name: z.string(),
  price: z.number(),
  in_stock: z.boolean(),
});

// Bad - fields that may not exist
const BadProduct = z.object({
  name: z.string(),
  price: z.number(),
  manufacturer: z.string(), // Page might not have this
  warranty: z.string(), // Page might not have this
});

3. Handle Missing Data

Use optional fields for data that might not exist:

from pydantic import BaseModel


class Product(BaseModel):
    name: str
    price: float
    discount_price: float | None = None  # Optional
    rating: float | None = None  # Optional

import { z } from 'zod';

const Product = z.object({
  name: z.string(),
  price: z.number(),
  discount_price: z.number().nullable().optional(), // Optional
  rating: z.number().nullable().optional(), // Optional
});

4. Scope Your Scrapes

Use selectors to focus on relevant content:

from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    # Scrape only the main article, not comments or sidebar
    content = session.scrape(selector="article.main")

import { NotteClient } from 'notte-sdk';

const client = new NotteClient({
  apiKey: process.env.NOTTE_API_KEY,
});

await client.Session().use(async (session) => {
  // Scrape only the main article, not comments or sidebar
  const content = await session.scrape({
    selector: 'article.main',
  });
});

Next Steps

Browser Sessions

Learn about session management

Search

Find pages before you fetch them

Vaults

Store credentials for authenticated scraping

Functions

Deploy scraping as serverless functions

Multi-step extraction

Use client.scrape() for a single URL, or session.scrape() after navigation and authentication:

authenticated_scrape.py

from notte_core.credentials import EMAIL, PASSWORD
from notte_sdk import NotteClient
from pydantic import BaseModel


class LinkedInConversation(BaseModel):
    recipient: str
    messages: list[str]


client = NotteClient()
vault = client.Vault(vault_id="<your-vault-id>")

with client.Session(vault_id=vault.vault_id) as session:
    # Log in: the vault replaces the EMAIL / PASSWORD placeholders with your real credentials
    session.execute(type="goto", url="https://www.linkedin.com/login")
    session.execute(type="form_fill", value={"email": EMAIL, "current_password": PASSWORD})
    session.execute(type="click", selector="button[type='submit']")

    # Navigate to your messages and extract the most recent conversation
    session.execute(type="goto", url="https://www.linkedin.com/messaging/")
    conversation = session.scrape(
        instructions="Extract the last 10 messages from my most recent conversation",
        response_format=LinkedInConversation,
    )
print(conversation)

Design the schema around the actual page content. Make fields optional when the source may omit them; request only data you need.

schema_design.py

from pydantic import BaseModel


class Product(BaseModel):
    product_url: str
    name: str
    price: float | None = None
    description: str | None = None
    image_url: str | None = None


class ProductList(BaseModel):
    products: list[Product]

Local Python extraction configuration

Install notte[llm] and set OPENROUTER_API_KEY for local structured extraction. The default model is google/gemini-3.5-flash-lite at https://openrouter.ai/api/v1. Cloud sessions use the platform’s server-side extraction configuration. For another OpenAI-compatible endpoint, set NOTTE_LLM_API_KEY and use the endpoint’s own model ID:

OpenAI: NOTTE_LLM_BASE_URL=https://api.openai.com/v1, NOTTE_LLM_MODEL=gpt-4o.
Gemini: NOTTE_LLM_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai, NOTTE_LLM_MODEL=gemini-3.5-flash-lite.
Ollama/custom: NOTTE_LLM_BASE_URL=http://localhost:11434/v1, NOTTE_LLM_MODEL set to your local model, and NOTTE_LLM_API_KEY=ollama for an unauthenticated local server. Ollama is documented but has not been live-tested.

NOTTE_LLM_API_KEY takes precedence over OPENROUTER_API_KEY; the latter is only used at the default OpenRouter URL. Custom endpoints require an explicit model, supplied through NOTTE_LLM_MODEL or LlmExtractor(model=...). A model passed to extract(..., model=...) applies to that call only. NOTTE_LLM_TEMPERATURE defaults to 0.0, NOTTE_LLM_NB_RETRIES_STRUCTURED_OUTPUT to 2, and NOTTE_LLM_CONTEXT_TOKENS to 128000. Document clipping estimates four characters per token. The client uses a 60-second HTTP timeout and retries transient errors after 2 and 5 seconds. Typed extraction tries strict schemas, then JSON-object output with the schema in the prompt; if the endpoint rejects JSON-object mode as well, the schema stays in the prompt alone.

Getting Started

Sessions

Authentication

Functions

Web API

Guides

Quick Start

Scraping Methods

Quick Scrape

Session-Based Scrape

Structured Extraction

Using Pydantic Models

Using Instructions Only

Extracting Lists

Nested Structures

Configuration Options

Content Filtering

Links

Scoped Scraping

Link Placeholders

Extraction Model

Return Types

Structured Response

Use Cases

Data Collection

Content Monitoring

Research and Analysis

Best Practices

1. Use Specific Instructions

2. Define Precise Schemas

3. Handle Missing Data

4. Scope Your Scrapes

Next Steps

Browser Sessions

Search

Vaults

Functions

Multi-step extraction

Local Python extraction configuration

​Quick Start

​Scraping Methods

​Quick Scrape

​Session-Based Scrape

​Structured Extraction

​Using Pydantic Models

​Using Instructions Only

​Extracting Lists

​Nested Structures

​Configuration Options

​Content Filtering

​Links

​Scoped Scraping

​Link Placeholders

​Extraction Model

​Return Types

​Structured Response

​Use Cases

​Data Collection

​Content Monitoring

​Research and Analysis

​Best Practices

​1. Use Specific Instructions

​2. Define Precise Schemas

​3. Handle Missing Data

​4. Scope Your Scrapes

​Next Steps

Browser Sessions

Search

Vaults

Functions

​Multi-step extraction

​Local Python extraction configuration

Quick Start

Scraping Methods

Quick Scrape

Session-Based Scrape

Structured Extraction

Using Pydantic Models

Using Instructions Only

Extracting Lists

Nested Structures

Configuration Options

Content Filtering

Links

Scoped Scraping

Link Placeholders

Extraction Model

Return Types

Structured Response

Use Cases

Data Collection

Content Monitoring

Research and Analysis

Best Practices

1. Use Specific Instructions

2. Define Precise Schemas

3. Handle Missing Data

4. Scope Your Scrapes

Next Steps

Multi-step extraction

Local Python extraction configuration