> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://platform.bctrl.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://platform.bctrl.ai/_mcp/server.

# Extract

> Extract structured data from an active browser page with Stagehand.

Ask Stagehand to read information from an active browser page. Use a natural
language instruction for simple extraction, or pass a JSON schema when your
application needs a predictable output shape.

## Extract page data

```ts
const result = await bctrl.tools.call("stagehand.extract", {
  pageId,
  instruction: "Extract the product name and price from the page.",
  schema: {
    type: "object",
    properties: {
      name: { type: "string" },
      price: { type: "number" },
    },
    required: ["name", "price"],
  },
}, { runtimeId: runtime.id });

console.log(result.value);
```

`pageId` is optional. If omitted, Stagehand uses the Runtime's active page.
`instruction` must be between 1 and 20,000 characters, and `timeoutMs` can be
up to `120000` milliseconds.

## Request parameters

| Parameter     | Type         | Required | Description                                                 |
| ------------- | ------------ | -------- | ----------------------------------------------------------- |
| `instruction` | `string`     | Yes      | What to extract, from 1 to 20,000 characters.               |
| `pageId`      | `PageId`     | No       | Page to inspect. Uses the active page when omitted.         |
| `timeoutMs`   | `integer`    | No       | Maximum extraction time in milliseconds. Maximum: `120000`. |
| `schema`      | `JsonObject` | No       | JSON schema for the extracted value.                        |

## Response

| Field         | Type              | Always present | Description                       |
| ------------- | ----------------- | -------------- | --------------------------------- |
| `value`       | `JsonValue`       | Yes            | Value extracted from the page.    |
| `cacheStatus` | `"HIT" \| "MISS"` | No             | Whether a cached result was used. |

`JsonValue` may be a string, number, boolean, `null`, array, or object. Pass a
schema when downstream code needs a stable structure.

## Run asynchronously

```ts
const call = await bctrl.tools.start("stagehand.extract", {
  pageId,
  instruction: "Extract all order line items and their quantities.",
}, { runtimeId: runtime.id });

const result = await bctrl.toolCalls.result(call.id, {
  waitSeconds: 120,
});
```

Use `bctrl.toolCalls.get(call.id)` to inspect progress or
`bctrl.toolCalls.cancel(call.id)` to cancel an active call.

## Next

* [Stagehand observe](/sdk/tools/stagehand/stagehand-observe) — find elements first
* [Stagehand act](/sdk/tools/stagehand/stagehand-act) — perform a browser action
* [AI models](/sdk/ai) — choose the model used by the Agent environment