Extract

Extract structured data from a webpage

What is extract()?

await stagehand.extract("extract the name of the repository");

extract() grabs structured data from a webpage. You can define your schema with Zod (TypeScript) or JSON. If you don’t want to define a schema, you can also call extract with just a natural language prompt, or call extract with no parameters.

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

When you use extract(), Stagehand will return a Promise<ExtractResult> with the following structure:

Basic Schema

When extracting with a schema, the return type is inferred from your Zod schema:

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

Example result:

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

Array

When extracting an array, you get an array of objects:

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

Example result:

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

Primitive

When extracting a single primitive value:

const price = await stagehand.extract(
  "extract the price",
  z.number()
);

Example result:

19.99

You can also extract strings, booleans, etc.:

const url = await stagehand.extract(
  "extract the contact page link",
  z.string().url()
);

Instruction Only

When calling with just an instruction (no schema):

const result = await stagehand.extract("extract the repository name");

Example result:

{
  extraction: "stagehand"
}

No Parameters

When calling with no parameters:

const result = await stagehand.extract();

Example result:

{
  pageText: "Accessibility Tree:\n[0-2] RootWebArea: Page Title\n  [0-37] scrollable\n    [0-118] body\n      ..."
}

This returns the accessibility tree representation of the page without LLM processing.

Advanced Configuration

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

const result = await stagehand.extract("extract the repository name", {
  model: "anthropic/claude-sonnet-4-5",
  timeout: 30000,
  selector: "//header" // Focus on specific area
});

Server-side Caching

serverCache only works when running with env: "BROWSERBASE". It has no effect in local environments.

When running on Browserbase, Stagehand automatically caches extract() results server-side. Repeated calls with the same inputs return instantly without consuming LLM tokens. Caching is enabled by default and can be controlled globally on the constructor or overridden per call:

// Disable server-side caching for the entire instance
const stagehand = new Stagehand({
  env: "BROWSERBASE",
  serverCache: false,
});

// Or disable it for a single call
const data = await stagehand.extract("extract the repository name", { serverCache: false });

// Check whether a result was served from cache
const result = await stagehand.extract("extract the page title");
console.log(result.cacheStatus); // "HIT" or "MISS"

For how the cache works, tuning the validation threshold, and best practices, see the Server Caching guide.

Targeted Extract

Pass a selector 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.

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

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

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

ignoreSelectors removes all matches for each selector, along with each matched node’s descendants. selector still scopes extraction to a single resolved subtree.

Visual Extract

Set screenshot: true when the extraction needs visual information from the current viewport in addition to the page accessibility tree.

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

screenshot: true captures the current viewport, not the full page. It is only supported with AI SDK clients.

Best practices

Extract with Context

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

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

Link Extraction

To extract links or URLs, define the relevant field as z.string().url().

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

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

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

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

Troubleshooting

Empty or partial results

Problem: extract() returns empty or incomplete data

Solutions:

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

Solution: Wait for content before extracting

// Wait for content before extracting
await stagehand.act("wait for the product listings to load");
const products = await stagehand.extract(
  "extract all product names and prices",
  z.array(z.object({
    name: z.string(),
    price: z.string()
  }))
);

Schema validation errors

Problem: Getting schema validation errors or type mismatches

Solutions:

• Use optional fields: Make fields optional with z.optional() if the data might not always be present
• Use flexible types: Consider using z.string() instead of z.number() for prices that might include currency symbols
• Add descriptions: Use .describe() to help the model understand field requirements

Solution: More flexible schema

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()
});

Inconsistent results

Problem: Extraction results vary between runs

Solutions:

• 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 stagehand.observe() to understand the page structure first

Solution: Validate with observe first

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

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

Performance issues

Problem: Extraction is slow or timing out

Solutions:

• 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 timeoutMs parameter for complex extractions

Solution: Break down large extractions

// 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 pageData = await stagehand.extract(
    "extract product data from the current page only",
    z.array(z.object({
      name: z.string(),
      price: z.number()
    })),
    { timeout: 60000 } // 60 second timeout
  );

  allData.push(...pageData);
}

Next steps

Act

Execute actions efficiently

Observe

Analyze pages and preview actions