Extract

What is `extract()`?

TypeScript
Python
Go

await stagehand.extract(
  "extract the name of the repository",
  z.object({ name: z.string() }),
);

class Repository(BaseModel):
    name: str


await stagehand.extract(
    "extract the name of the repository",
    Repository,
)

type repository struct {
	Name string `json:"name"`
}


extracted, err := stagehand.Extract[repository](
	ctx,
	client,
	"extract the name of the repository",
	nil,
)

extract() grabs structured data from a webpage. Every call takes an instruction and an output shape: Zod in TypeScript, Pydantic in Python, and a Go type parameter whose JSON Schema Stagehand derives automatically. Stagehand validates the result against that shape before returning it, so what you get back is already typed.

Why use `extract()`?

Structured

Turn messy webpage data into clean objects that follow a schema.

Resilient

Build resilient extractions that don’t break when the website changes

Return value

extract() returns a result with two fields: data holds the extracted value, and metadata carries the action ID and server-side cache status. The shape of data follows the schema or Go type you supplied:

Basic schema
Array
Primitive

When extracting with an object schema, the return type is inferred from that schema:

TypeScript
Python
Go

const { data } = await stagehand.extract(
  "extract product details",
  z.object({
    name: z.string(),
    price: z.number(),
    inStock: z.boolean(),
  }),
);

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


result = await stagehand.extract(
    "extract product details",
    Product,
)

type product struct {
	Name    string  `json:"name"`
	Price   float64 `json:"price"`
	InStock bool    `json:"in_stock"`
}


extracted, err := stagehand.Extract[product](
	ctx,
	client,
	"extract product details",
	nil,
)

Example result:

TypeScript
Python
Go

{
  name: "Wireless Mouse",
  price: 29.99,
  inStock: true
}

Product(name="Wireless Mouse", price=29.99, in_stock=True)

result := product{Name: "Wireless Mouse", Price: 29.99, InStock: true}
fmt.Println(result.Name, result.Price, result.InStock)

To extract a list, wrap it in a field on your schema:

TypeScript
Python
Go

const { data } = await stagehand.extract(
  "extract all apartment listings",
  z.object({
    apartments: z.array(
      z.object({
        address: z.string(),
        price: z.string(),
        sqft: z.number(),
      }),
    ),
  }),
);

class Apartment(BaseModel):
    address: str
    price: str
    sqft: int


class Apartments(BaseModel):
    apartments: list[Apartment]


result = await stagehand.extract(
    "extract all apartment listings",
    Apartments,
)

type apartment struct {
	Address string `json:"address"`
	Price   string `json:"price"`
	Sqft    int    `json:"sqft"`
}

type apartments struct {
	Apartments []apartment `json:"apartments"`
}


extracted, err := stagehand.Extract[apartments](
	ctx,
	client,
	"extract all apartment listings",
	nil,
)

Example result:

TypeScript
Python
Go

{
  apartments: [
    {
      address: "123 Main St",
      price: "$1,200/mo",
      sqft: 750
    },
    {
      address: "456 Oak Ave",
      price: "$1,500/mo",
      sqft: 900
    }
  ]
}

Apartments(apartments=[
    Apartment(address="123 Main St", price="$1,200/mo", sqft=750),
    Apartment(address="456 Oak Ave", price="$1,500/mo", sqft=900),
])

result := apartments{Apartments: []apartment{
	{Address: "123 Main St", Price: "$1,200/mo", Sqft: 750},
	{Address: "456 Oak Ave", Price: "$1,500/mo", Sqft: 900},
}}
fmt.Println(result.Apartments[0].Address, result.Apartments[0].Sqft)

To extract a single value, give it a named field:

TypeScript
Python
Go

const { data } = await stagehand.extract(
  "extract the price",
  z.object({ price: z.number() }),
);

class Price(BaseModel):
    price: float


result = await stagehand.extract(
    "extract the price",
    Price,
)

type price struct {
	Price float64 `json:"price"`
}


extracted, err := stagehand.Extract[price](
	ctx,
	client,
	"extract the price",
	nil,
)

Example result:

TypeScript
Python
Go

{
  price: 19.99
}

Price(price=19.99)

result := price{Price: 19.99}
fmt.Println(result.Price)

You can also extract strings, booleans, and URLs:

TypeScript
Python
Go

const { data } = await stagehand.extract(
  "extract the contact page link",
  z.object({ url: z.url() }),
);

from pydantic import AnyUrl


class ContactLink(BaseModel):
    url: AnyUrl


result = await stagehand.extract(
    "extract the contact page link",
    ContactLink,
)

type contactLink struct {
	URL string `json:"url" jsonschema:"format=uri"`
}


extracted, err := stagehand.Extract[contactLink](
	ctx,
	client,
	"extract the contact page link",
	nil,
)

Advanced configuration

You can pass additional options to configure the model, timeout, locator scope, and whether to include a screenshot:

TypeScript
Python
Go

const page = await stagehand.browser.context.activePage();

const result = await stagehand.extract(
  "extract the repository name",
  z.object({ name: z.string() }),
  {
    model: {
      modelName: "anthropic/claude-sonnet-4-6",
      apiKey: process.env.ANTHROPIC_API_KEY,
    },
    timeout: 30000,
    locator: page.locator("xpath=//header"), // Focus on specific area
  },
);

import os

from stagehand import ModelConfig

page = await stagehand.browser.context.active_page()

result = await stagehand.extract(
    "extract the repository name",
    Repository,
    model=ModelConfig(
        model_name="anthropic/claude-sonnet-4-6",
        api_key=os.environ["ANTHROPIC_API_KEY"],
    ),
    timeout=30000,
    locator=page.locator("xpath=//header"),  # Focus on specific area
)

modelAPIKey := os.Getenv("ANTHROPIC_API_KEY")
model := stagehand.ModelConfig{
	ModelName: "anthropic/claude-sonnet-4-6",
	APIKey:    &modelAPIKey,
}
timeout := 30000.0

result, err := stagehand.Extract[repository](ctx, client, "extract the repository name", &stagehand.StagehandClientExtractOptions{
	Page:    page,
	Model:   &model,
	Timeout: &timeout,
	Locator: page.Locator("xpath=//header"), // Focus on specific area
})
if err != nil {
	return err
}

fmt.Println(result.Data.Name)

Server-side caching

cache requires a Browserbase browser and a Browserbase API key. It has no effect on local browsers.

When running on Browserbase, Stagehand can cache extract() results server-side. Repeated calls with the same inputs return instantly without consuming LLM tokens. Enable caching on Stagehand.create() and override it per call: Locator-scoped extractions, including calls with locator or ignoreLocators, bypass the server-side cache and report metadata.cache.status as DISABLED.

TypeScript
Python
Go

import { browserbase, Stagehand } from "@browserbasehq/stagehand";

// Enable server-side caching for the entire instance
const browser = await browserbase.launch({ apiKey: process.env.BROWSERBASE_API_KEY });

const stagehand = await Stagehand.create({
  browser,
  cache: true,
});

// Or disable it for a single call
const result = await stagehand.extract(
  "extract the repository name",
  z.object({ name: z.string() }),
  { cache: false },
);

// Cache status travels on the result metadata
console.log(result.metadata.cache.status); // "HIT", "MISS", or "DISABLED"

import os

from stagehand import Stagehand, browserbase

# Enable server-side caching for the entire instance
browser = await browserbase.launch(api_key=os.environ["BROWSERBASE_API_KEY"])

stagehand = await Stagehand.create(
    browser=browser,
    cache=True,
)

# Or disable it for a single call
result = await stagehand.extract(
    "extract the repository name",
    Repository,
    cache=False,
)

# Cache status travels on the result metadata
print(result.metadata.cache.status)  # "HIT", "MISS", or "DISABLED"

// Enable server-side caching for the entire instance
apiKey := os.Getenv("BROWSERBASE_API_KEY")
instanceCache := stagehand.CacheEnabled(true)

browser, err := stagehand.LaunchBrowserbase(ctx, stagehand.BrowserbaseLaunchOptions{
	APIKey: apiKey,
})
if err != nil {
	return err
}

client, err := stagehand.Create(ctx, stagehand.CreateOptions{
	Browser: browser,
	Cache:   &instanceCache,
})
if err != nil {
	return err
}

// Or disable it for a single call
off := stagehand.CacheEnabled(false)
result, err := stagehand.Extract[repository](ctx, client, "extract the repository name", &stagehand.StagehandClientExtractOptions{
	Cache: &off,
})
if err != nil {
	return err
}

// Cache status travels on the result metadata
fmt.Println(result.Metadata.Cache.Status) // "HIT", "MISS", or "DISABLED"

Targeted extract

Pass a page locator to extract to target a specific element on the page.

This helps reduce the context passed to the LLM, optimizing token usage/speed and improving accuracy.

TypeScript
Python
Go

const page = await stagehand.browser.context.activePage();

const { data: tableData } = await stagehand.extract(
  "Extract the values of the third row",
  z.object({
    values: z.array(z.string()),
  }),
  {
    locator: page.locator("xpath=/html/body/div/table/"),
  },
);

class TableRow(BaseModel):
    values: list[str]


page = await stagehand.browser.context.active_page()

table_data = (await stagehand.extract(
    "Extract the values of the third row",
    TableRow,
    locator=page.locator("xpath=/html/body/div/table/"),
)).data

type tableRow struct {
	Values []string `json:"values"`
}

tableData, err := stagehand.Extract[tableRow](
	ctx,
	client,
	"Extract the values of the third row",
	&stagehand.StagehandClientExtractOptions{
		Page:    page,
		Locator: page.Locator("xpath=/html/body/div/table/"),
	},
)

You can also exclude specific nodes (including their descendant nodes) with ignored locators.

TypeScript
Python
Go

const page = await stagehand.browser.context.activePage();

const { data: article } = await stagehand.extract(
  "extract the article title and body",
  z.object({
    title: z.string(),
    body: z.string(),
  }),
  {
    ignoreLocators: [
      page.locator(".ad"),
      page.locator(".newsletter-modal"),
      page.locator("nav.related-posts"),
    ],
  },
);

class Article(BaseModel):
    title: str
    body: str


page = await stagehand.browser.context.active_page()

article = (await stagehand.extract(
    "extract the article title and body",
    Article,
    ignore_locators=[
        page.locator(".ad"),
        page.locator(".newsletter-modal"),
        page.locator("nav.related-posts"),
    ],
)).data

type article struct {
	Title string `json:"title"`
	Body  string `json:"body"`
}


extracted, err := stagehand.Extract[article](
	ctx,
	client,
	"extract the article title and body",
	&stagehand.StagehandClientExtractOptions{
		Page: page,
		IgnoreLocators: []*stagehand.PageLocator{
			page.Locator(".ad"),
			page.Locator(".newsletter-modal"),
			page.Locator("nav.related-posts"),
		},
	},
)

ignoreLocators remove each resolved locator target and its descendants from the snapshot. A locator without nth removes all matching targets; a locator with nth removes only that indexed match. The locator option scopes extraction to one resolved subtree, using nth when present. Scoped extract currently supports CSS and XPath locators. text= locators are supported by locator methods, but not yet by extract snapshot scoping.

Visual extract

Turn the screenshot option on when the extraction needs visual information from the current viewport in addition to the page accessibility tree.

TypeScript
Python
Go

const { data: saleBadge } = await stagehand.extract(
  "extract the text shown in the visible sale badge",
  z.object({
    text: z.string(),
  }),
  {
    screenshot: true,
  },
);

class SaleBadge(BaseModel):
    text: str


sale_badge = (await stagehand.extract(
    "extract the text shown in the visible sale badge",
    SaleBadge,
    screenshot=True,
)).data

type saleBadge struct {
	Text string `json:"text"`
}


screenshot := true

saleBadgeData, err := stagehand.Extract[saleBadge](
	ctx,
	client,
	"extract the text shown in the visible sale badge",
	&stagehand.StagehandClientExtractOptions{
		ExtractOptions: stagehand.ExtractOptions{Screenshot: &screenshot},
	},
)

The screenshot option captures the current viewport, not the full page. Visual extractions always bypass the server-side cache, because a cache key is built from DOM state and cannot represent the pixels the model saw.

Best practices

Extract with context

You can provide additional context to your schema to help the model extract the data more accurately.

TypeScript
Python
Go

const { data } = await stagehand.extract(
  "Extract ALL the apartment listings and their details, including address, price, and square feet.",
  z.object({
    apartments: z.array(
      z.object({
        address: z.string().describe("the address of the apartment"),
        price: z.string().describe("the price of the apartment"),
        squareFeet: z.string().describe("the square footage of the apartment"),
      }),
    ),
  }),
);

from pydantic import BaseModel, Field


class Apartment(BaseModel):
    address: str = Field(description="the address of the apartment")
    price: str = Field(description="the price of the apartment")
    square_feet: str = Field(description="the square footage of the apartment")


class Apartments(BaseModel):
    apartments: list[Apartment]


result = await stagehand.extract(
    (
        "Extract ALL the apartment listings and their details, "
        "including address, price, and square feet."
    ),
    Apartments,
)

type apartment struct {
	Address    string `json:"address" jsonschema:"description=the address of the apartment"`
	Price      string `json:"price" jsonschema:"description=the price of the apartment"`
	SquareFeet string `json:"square_feet" jsonschema:"description=the square footage of the apartment"`
}

type apartments struct {
	Apartments []apartment `json:"apartments"`
}

// Optional JSON Schema constraints live in jsonschema struct tags.

extracted, err := stagehand.Extract[apartments](
	ctx,
	client,
	"Extract ALL the apartment listings and their details, including address, price, and square feet.",
	nil,
)

Link extraction

To extract links or URLs, define the relevant field as a URL type.

Here is how an extract call might look for extracting a link or URL. This also works for image links.

TypeScript
Python
Go

const { data } = await stagehand.extract(
  "extract the link to the 'contact us' page",
  // note the usage of z.url() for URL validation
  z.object({ contactLink: z.url() }),
);

console.log("the link to the contact us page is: ", data.contactLink);

from pydantic import AnyUrl, BaseModel


class ContactLink(BaseModel):
    # note the usage of AnyUrl for URL validation
    contact_link: AnyUrl


result = await stagehand.extract(
    "extract the link to the 'contact us' page",
    ContactLink,
)

print("the link to the contact us page is: ", result.data.contact_link)

type contactLink struct {
	ContactLink string `json:"contact_link" jsonschema:"format=uri"`
}

// The jsonschema tag adds the "format": "uri" constraint.

extracted, err := stagehand.Extract[contactLink](
	ctx,
	client,
	"extract the link to the 'contact us' page",
	nil,
)
if err != nil {
	return err
}

fmt.Println("the link to the contact us page is: ", extracted.Data.ContactLink)

Inside Stagehand, extracting links works by asking the LLM to select an ID. Stagehand looks up that ID in a mapping of IDs to URLs. When logging the LLM trace, you should expect to see IDs. The actual URLs will be included in the final result.

Troubleshooting

Empty or partial results

Problem: extract() returns empty or incomplete dataSolutions:

Check your instruction clarity: Make sure your instruction is specific and describes exactly what data you want to extract
Verify the data exists: Use observe() first to confirm the data is present on the page
Wait for dynamic content: If the page loads content dynamically, wait for it before extracting

Solution: Wait for content before extracting

TypeScript
Python
Go

// waitForSelector reports whether the selector matched, so check it
// before extracting: a timeout resolves to false without throwing.
const listingReady = await page.waitForSelector(".product-listing");
if (!listingReady) {
  throw new Error("timed out waiting for .product-listing");
}

const { data } = await stagehand.extract(
  "extract all product names and prices",
  z.object({
    products: z.array(z.object({
      name: z.string(),
      price: z.string(),
    })),
  }),
);

# wait_for_selector reports whether the selector matched, so check it
# before extracting: a timeout returns False without raising.
listing_ready = await page.wait_for_selector(".product-listing")
if not listing_ready:
    raise TimeoutError("timed out waiting for .product-listing")


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


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


result = await stagehand.extract(
    "extract all product names and prices",
    Products,
)

// WaitForSelector returns (matched, error), so check matched before
// extracting: a timeout reports false without returning an error.
matched, err := page.WaitForSelector(ctx, ".product-listing", nil)
if err != nil {
	return err
}
if !matched {
	return fmt.Errorf("timed out waiting for .product-listing")
}

type product struct {
	Name  string `json:"name"`
	Price string `json:"price"`
}

type products struct {
	Products []product `json:"products"`
}


extracted, err := stagehand.Extract[products](
	ctx,
	client,
	"extract all product names and prices",
	nil,
)
if err != nil {
	return err
}

fmt.Println("extracted", len(extracted.Data.Products), "products")

Schema validation errors

Problem: Getting schema validation errors or type mismatchesSolutions:

Use optional fields: Make fields optional if the data might not always be present
Use flexible types: Consider using a string instead of a number for prices that might include currency symbols
Add descriptions: Describe each field to help the model understand its requirements

Solution: More flexible schema

TypeScript
Python
Go

const schema = z.object({
  price: z.string().describe("price including currency symbol, e.g., '$19.99'"),
  availability: z.string().optional().describe("stock status if available"),
  rating: z.number().optional(),
});

class ProductDetails(BaseModel):
    price: str = Field(description="price including currency symbol, e.g., '$19.99'")
    availability: str | None = Field(default=None, description="stock status if available")
    rating: float | None = None

// Optional fields are pointers, and descriptions live in the JSON Schema
type productDetails struct {
	Price        string   `json:"price" jsonschema:"description=price including currency symbol such as $19.99"`
	Availability *string  `json:"availability,omitempty" jsonschema:"description=stock status if available"`
	Rating       *float64 `json:"rating,omitempty"`
}

Inconsistent results

Problem: Extraction results vary between runsSolutions:

Be more specific in instructions: Instead of “extract prices”, use “extract the numerical price value for each item”
Use context in schema descriptions: Add field descriptions to guide the model
Combine with observe: Use observe() to understand the page structure first

Solution: Validate with observe first

TypeScript
Python
Go

// First observe to understand the page structure
const { data: elements } = await stagehand.observe("find all product listings");
console.log("Found elements:", elements.map(e => e.description));

// Then extract with specific targeting
const { data } = await stagehand.extract(
  "extract name and price from each product listing shown on the page",
  z.object({
    products: z.array(z.object({
      name: z.string().describe("the product title or name"),
      price: z.string().describe("the price as displayed, including currency"),
    })),
  }),
);

# First observe to understand the page structure
observed = await stagehand.observe("find all product listings")
print("Found elements:", [element.description for element in observed.data])


# Then extract with specific targeting
class Product(BaseModel):
    name: str = Field(description="the product title or name")
    price: str = Field(description="the price as displayed, including currency")


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


result = await stagehand.extract(
    "extract name and price from each product listing shown on the page",
    Products,
)

// First observe to understand the page structure
instruction := "find all product listings"
observed, err := client.Observe(ctx, &instruction, nil)
if err != nil {
	return err
}
for _, element := range observed.Data {
	fmt.Println("Found element:", element.Description)
}

// Then extract with specific targeting
type product struct {
	Name  string `json:"name"`
	Price string `json:"price"`
}

type products struct {
	Products []product `json:"products"`
}


extracted, err := stagehand.Extract[products](
	ctx,
	client,
	"extract name and price from each product listing shown on the page",
	nil,
)
if err != nil {
	return err
}

for _, item := range extracted.Data.Products {
	fmt.Println(item.Name, item.Price)
}

Performance issues

Problem: Extraction is slow or timing outSolutions:

Reduce scope: Extract smaller chunks of data in multiple calls rather than everything at once
Use targeted instructions: Be specific about which part of the page to focus on
Consider pagination: For large datasets, extract one page at a time
Increase timeout: Use the timeout option for complex extractions

Solution: Break down large extractions

TypeScript
Python
Go

// Instead of extracting everything at once
const allData = [];
const pageNumbers = [1, 2, 3, 4, 5];

for (const pageNum of pageNumbers) {
  await stagehand.act(`navigate to page ${pageNum}`);

  const { data } = await stagehand.extract(
    "extract product data from the current page only",
    z.object({
      products: z.array(z.object({
        name: z.string(),
        price: z.number(),
      })),
    }),
    { timeout: 60000 }, // 60 second timeout
  );

  allData.push(...data.products);
}

# Instead of extracting everything at once
all_data = []
page_numbers = [1, 2, 3, 4, 5]

for page_num in page_numbers:
    await stagehand.act(f"navigate to page {page_num}")

    result = await stagehand.extract(
        "extract product data from the current page only",
        Products,
        timeout=60000,  # 60 second timeout
    )

    all_data.extend(result.data.products)

type product struct {
	Name  string  `json:"name"`
	Price float64 `json:"price"`
}

type products struct {
	Products []product `json:"products"`
}


// Instead of extracting everything at once
var allData []product
timeout := 60000.0 // 60 second timeout

for pageNum := 1; pageNum <= 5; pageNum++ {
	if _, err := client.Act(ctx, stagehand.ActInstruction(fmt.Sprintf("navigate to page %d", pageNum)), nil); err != nil {
		return err
	}

	extracted, err := stagehand.Extract[products](
		ctx,
		client,
		"extract product data from the current page only",
		&stagehand.StagehandClientExtractOptions{
			ExtractOptions: stagehand.ExtractOptions{Timeout: &timeout},
		},
	)
	if err != nil {
		return err
	}

	allData = append(allData, extracted.Data.Products...)
}

First steps

The basics

Configuration

Best practices

Migration guide

SDK reference

What is `extract()`?

Why use `extract()`?

Structured

Resilient

Return value

Advanced configuration

Server-side caching

Targeted extract

Visual extract

Best practices

Extract with context

Link extraction

Troubleshooting

Next steps

Act

Observe

​What is extract()?

​Why use extract()?

Structured

Resilient

​Return value

​Advanced configuration

​Server-side caching

​Targeted extract

​Visual extract

​Best practices

​Extract with context

​Link extraction

​Troubleshooting

​Next steps

Act

Observe

What is `extract()`?

Why use `extract()`?

Return value

Advanced configuration

Server-side caching

Targeted extract

Visual extract

Best practices

Extract with context

Link extraction

Troubleshooting

Next steps