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.

It runs locally with your own browser or against Browserbase’s cloud browsers. For stubborn sites and fast-changing UIs, Stagehand cuts the time spent patching selectors after every redesign.

What is Stagehand?

Stagehand is an open-source TypeScript library that combines browser automation with LLM reasoning. You keep Playwright’s control flow and page object, but use natural-language actions for the parts that would otherwise need brittle selectors. It supports OpenAI, Anthropic and other models for the reasoning step.

How do you install and set it up?

1. npm install @browserbasehq/stagehand
2. Set an API key for your chosen model (e.g. OPENAI_API_KEY).
3. Optionally set Browserbase credentials for cloud browsers, or run locally.
4. Create a Stagehand instance pointed at a page.
5. Call act() with a plain instruction and await it.

First runs make a model call per action, which adds a second or two.

How do act, extract and observe differ?

• act performs an action: “type the email into the signup field and submit”.
• extract pulls structured data from the page using a schema.
• observe returns the available actions on a page so you can plan.

Use extract for scraping, act for tapping through a flow, and observe when you want to see what the page offers before deciding.

How do you extract structured data?

Define a schema (a Zod object or JSON schema) and pass it to extract(). Stagehand returns an object matching the schema, so you get typed fields instead of raw HTML to parse. This is the cleanest way to turn a listing page into rows of data.

How do you keep it fast and cheap?

Every act/extract call costs tokens. Two habits help: cache actions so a repeated step does not re-query the model, and fall back to plain Playwright for stable steps you do not need AI for. A hybrid script — AI for the fragile parts, selectors for the rest — is both cheaper and more reliable than a fully AI-driven one.

What are the limitations?

AI actions can misfire on ambiguous instructions or heavily scripted sites, and they add latency. Complex multi-step flows may need explicit waits and error handling. It is not a magic scraper for anti-bot walls; you still need compliant, rate-limited access.

Key Takeaways

• Stagehand adds AI act/extract/observe to Playwright.
• Install with npm and set a model API key.
• extract returns schema-typed data; act runs natural-language steps.
• Cache actions and keep AI only for fragile steps to cut cost.
• It complements Playwright rather than replacing it.

Last updated October 2026. More at Stagehand.