Skip to main content

​
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 do not 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

​
Using extract()

You can use extract() to extract structured data from a webpage. You can define your schema with zod (TypeScript) or JSON. If you do not want to define a schema, you can also call extract with just a natural language prompt, or call extract with no parameters. 
const result = await stagehand.extract("extract the product details");

​
Return value of extract()?

When you use extract(), Stagehand will return a Promise<ExtractResult> with the following structure:
  • Basic Schema
  • Array
  • Primitive
  • Instruction Only
  • No Parameters
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
}

​
Advanced Configuration

You can pass additional options to configure the model, timeout, and selector scope: 
const result = await stagehand.extract("extract the repository name", {
  model: "anthropic/claude-sonnet-4-5",
  timeout: 30000,
  selector: "//header" // Focus on specific area
});

​
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/" 
  }
);

​
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"),
    })
  )
);
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

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 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()
  }))
);
Problem: Getting schema validation errors or type mismatchesSolutions:
  • 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()
});
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 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")
  }))
);
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 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