How to Scrape Structured Data with Stagehand Extract

Scraping with CSS selectors is a maintenance treadmill — one markup change and every scraper you wrote stops returning data. Stagehand takes a different route: you define the shape of the data you want, and its extract() method finds it on the page. The output is typed JSON instead of raw HTML you have to parse by hand.

This builds on the basic Stagehand setup. If you have not installed it yet, do the Playwright walkthrough first — here we focus on extraction patterns and cost control.

How does extract work?

You pass a schema and an instruction. Stagehand uses the page content and the instruction to return an object that matches the schema. Define the schema once and reuse it across pages on the same site, which is what makes it resilient to layout tweaks.

How do you define a schema?

1. Pick the fields you actually need — title, price, rating, URL.
2. Write them as a Zod object (or JSON schema) with correct types.
3. Keep field names clear and stable; downstream code depends on them.
4. Pass the schema plus a short instruction to extract().
5. Validate the returned object before storing it.

Typed fields (numbers as numbers, not strings) save cleanup later.

How do you scrape a list of items?

For listing pages, define an array schema and let extract return an array of objects. For detail pages, loop over URLs and extract one object each. Keep the two schemas separate — a listing card and a detail page rarely share the same fields.

How do you keep the token cost down?

• Extract once per page, not once per field.
• Trim the page first — scroll to load, then take a snapshot rather than feeding full raw HTML.
• Cache results by URL so a re-run skips pages you already have.
• Use plain Playwright for navigation and waits, AI only for the extraction.

A few hundred pages is cheap; tens of thousands needs caching and batching.

What breaks, and how do you handle it?

Dynamic pages that load content after the first paint need a wait before extraction, or you capture an empty shell. Some pages hide data behind logins or anti-bot checks — Stagehand does not bypass those, and you should respect terms of service and robots rules. Always validate output: a model can return a plausible but wrong value, so add a sanity check on numbers.

Stagehand vs. classic scrapers

For a static site with stable markup, a plain HTML parser is faster and free. Reach for Stagehand when the markup churns, the data is spread across messy layouts, or you would otherwise write dozens of fragile selectors. It is a resilience tool, not a speed tool.

Key Takeaways

• Stagehand extract() returns schema-typed JSON from a page.
• Define a reusable schema per page type, validate before storing.
• Extract once per page and cache by URL to control token cost.
• Wait for dynamic content before extracting.
• Use plain parsers for stable sites; Stagehand for churning layouts.

Last updated October 2026. More at Stagehand.