extract()

Complete API reference for the extract() method

Extract

See how to use extract() to extract structured data from web pages

Method Signatures

TypeScript

// No parameters (raw page content)
await stagehand.extract(): Promise<{ pageText: string }>

// Options only (for example, for targeted extraction)
await stagehand.extract(options: ExtractOptions): Promise<{ pageText: string }>

// String instruction only
await stagehand.extract(instruction: string): Promise<{ extraction: string }>

// With schema
await stagehand.extract<T extends ZodTypeAny>(
  instruction: string,
  schema: T,
  options?: ExtractOptions
): Promise<z.infer<T>>

ExtractOptions Interface:

interface ExtractOptions {
  model?: ModelConfiguration;
  timeout?: number;
  selector?: string;
  ignoreSelectors?: string[];
  page?: PlaywrightPage | PuppeteerPage | PatchrightPage | Page;
  serverCache?: boolean;
}

// ModelConfiguration can be either a string or an object
type ModelConfiguration =
  | string  // Format: "provider/model" (e.g., "openai/gpt-5-mini", "anthropic/claude-sonnet-4-5")
  | {
      modelName: string;  // The model name
      apiKey?: string;    // Optional: API key override
      baseURL?: string;   // Optional: Base URL override
      // Additional provider-specific options
    }

Parameters

instruction · string

Natural language description of what data to extract. If omitted with no schema, returns raw page text.

schema · ZodTypeAny

Zod schema defining the structure of data to extract. Ensures type safety and validation. The return type is automatically inferred from the schema.

model · ModelConfiguration

Configure the AI model to use for this action. Can be either:

• A string in the format "provider/model" (e.g., openai/gpt-5, google/gemini-2.5-flash)
• An object with detailed configuration

Show Model Configuration Object

modelName · string · required

The model name (e.g., anthropic/claude-sonnet-4-5, google/gemini-2.5-flash)

apiKey · string

API key for the model provider (overrides default)

baseURL · string

Base URL for the API endpoint (for custom endpoints or proxies)

timeout · number

Maximum time in milliseconds to wait for the extraction to complete. Default varies by configuration.

selector · string

Optional selector (XPath, CSS selector, etc.) to limit extraction scope to a specific part of the page. Reduces token usage and improves accuracy.

ignoreSelectors · string[]

Optional list of selectors to exclude from the extracted snapshot before extraction runs. Each selector removes all matching elements and their descendants.

ignoreSelectors applies to all matches for each selector. selector keeps its single-target scoping behavior.

page · PlaywrightPage | PuppeteerPage | PatchrightPage | Page

Optional: Specify which page to perform the extraction on. Supports multiple browser automation libraries:

• Stagehand Page: Native Stagehand Page objects
• Playwright: Playwright Page objects
• Puppeteer: Puppeteer Page objects
• Patchright: Patchright Page objects

If not specified, defaults to the current “active” page in your Stagehand instance.

serverCache · boolean

Override the instance-level serverCache setting for this request. When true, enables server-side caching. When false, disables it.

Only applies when env is "BROWSERBASE". Has no effect in local environments.

Defaults to the value set on the Stagehand constructor (which itself defaults to true).

Built-in Support

Iframe and Shadow DOM interactions are supported out of the box. Stagehand automatically handles iframe traversal and shadow DOM elements without requiring additional configuration or flags.

Response Types

With Schema

Returns: Promise<z.infer<T> & { cacheStatus?: "HIT" | "MISS" }> where T is your schema

The returned object will be strictly typed according to your Zod schema definition. The optional cacheStatus field indicates whether the result was served from the server-side cache ("HIT") or computed fresh ("MISS"). Only present when running with env: "BROWSERBASE" and server-side caching is enabled.

String Only

Returns: Promise<{ extraction: string; cacheStatus?: "HIT" | "MISS" }>

extraction: Simple string extraction without schema validation. The optional cacheStatus field indicates cache hit or miss when using Browserbase with server-side caching.

No Parameters

Returns: Promise<{ pageText: string }>

pageText: Raw accessibility tree representation of page content.

Code Examples

Single Object

import { Stagehand } from "@browserbasehq/stagehand";
import { z } from 'zod';

// Initialize with Browserbase (API key from environment variable)
// Set BROWSERBASE_API_KEY in your environment
const stagehand = new Stagehand({ env: "BROWSERBASE" });
await stagehand.init();
const page = stagehand.context.pages()[0];

await page.goto("https://example.com/product");

// Schema definition
const ProductSchema = z.object({
  name: z.string(),
  price: z.number(),
  inStock: z.boolean()
});

// Extraction with v3 API
const product = await stagehand.extract(
  "extract product details", 
  ProductSchema
);

Example Response

{
  "name": "Product Name",
  "price": 100,
  "inStock": true
}

Arrays

import { z } from 'zod';

// Schema definition
const ApartmentListingsSchema = z.array(
  z.object({
    address: z.string(),
    price: z.string(),
    bedrooms: z.number()
  })
);

// Extraction with v3 API
const listings = await stagehand.extract(
  "extract all apartment listings",
  ApartmentListingsSchema
);

Example Response

[
  {
    "address": "123 Main St",
    "price": "$100,000",
    "bedrooms": 3
  },
  {
    "address": "456 Elm St",
    "price": "$150,000",
    "bedrooms": 2
  }
]

URLs

import { z } from 'zod';

// Schema definition
const NavigationSchema = z.object({
  links: z.array(z.object({
    text: z.string(),
    url: z.string().url()  // URL validation
  }))
});

// Extraction with v3 API
const links = await stagehand.extract(
  "extract navigation links",
  NavigationSchema
);

Example Response

{
  "links": [
    {
      "text": "Home",
      "url": "https://example.com"
    }
  ]
}

Scoped

import { z } from 'zod';

const ProductSchema = z.object({
  name: z.string(),
  price: z.number(),
  description: z.string()
});

// Extract from specific page section with v3 API
const data = await stagehand.extract(
  "extract product info from this section",
  ProductSchema,
  { selector: "/html/body/div/div" }
);

Example Response

{
  "name": "Product Name",
  "price": 100,
  "description": "Product description"
}

Schema-less

// String only extraction
const title = await stagehand.extract("get the page title");
// Returns: { extraction: "Page Title" }

// Raw page content
const content = await stagehand.extract();
// Returns: { pageText: "Accessibility Tree: ..." }

Example Response

{
  "extraction": "Page Title"
}

Advanced

import { z } from 'zod';

// Schema with descriptions and validation
const ProductSchema = z.object({
  price: z.number().describe("Product price in USD"),
  rating: z.number().min(0).max(5).describe("Customer rating out of 5"),
  available: z.boolean().describe("Whether product is in stock"),
  tags: z.array(z.string()).optional()
});

// Nested schema
const EcommerceSchema = z.object({
  product: z.object({
    name: z.string(),
    price: z.object({
      current: z.number(),
      original: z.number().optional()
    })
  }),
  reviews: z.array(z.object({
    rating: z.number(),
    comment: z.string()
  }))
});

Example Response

{
  "product": {
    "name": "Product Name",
    "price": {
      "current": 100,
      "original": 120
    }
  },
  "reviews": [
    {
      "rating": 4,
      "comment": "Great product!"
    }
  ]
}

Additional Examples

Custom Model

import { z } from 'zod';

const DataSchema = z.object({
  title: z.string(),
  content: z.string()
});

// Using string format
const data1 = await stagehand.extract(
  "extract article data",
  DataSchema,
  { model: "openai/gpt-5-mini" }
);

// Using object format with custom configuration
const data2 = await stagehand.extract(
  "extract article data",
  DataSchema,
  {
    model: {
      modelName: "claude-sonnet-4-6",
      apiKey: process.env.ANTHROPIC_API_KEY
    }
  }
);

Multi-Page

import { z } from 'zod';

const page1 = stagehand.context.pages()[0];
const page2 = await stagehand.context.newPage();

const Schema = z.object({ title: z.string() });

const data1 = await stagehand.extract("get title", Schema, { page: page1 });
const data2 = await stagehand.extract("get title", Schema, { page: page2 });

Error Types

The following errors may be thrown by the extract() method:

• StagehandError - Base class for all Stagehand-specific errors
• ZodSchemaValidationError - Extracted data does not match the provided Zod schema
• StagehandDomProcessError - Error occurred while processing the DOM
• StagehandEvalError - Error occurred while evaluating JavaScript in the page context
• StagehandIframeError - Unable to resolve iframe for the target element
• ContentFrameNotFoundError - Unable to obtain content frame for the selector
• XPathResolutionError - XPath does not resolve in the current page or frames
• StagehandShadowRootMissingError - No shadow root present on the resolved host element
• LLMResponseError - Error in LLM response processing
• MissingLLMConfigurationError - No LLM API key or client configured
• UnsupportedModelError - The specified model is not supported for this operation
• InvalidAISDKModelFormatError - Model string does not follow the required provider/model format