Extract

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

1
const result = await bctrl.tools.call("stagehand.extract", {
2
  pageId,
3
  instruction: "Extract the product name and price from the page.",
4
  schema: {
5
    type: "object",
6
    properties: {
7
      name: { type: "string" },
8
      price: { type: "number" },
9
    },
10
    required: ["name", "price"],
11
  },
12
}, { runtimeId: runtime.id });
13
14
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

Response

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

Run asynchronously

1
const call = await bctrl.tools.start("stagehand.extract", {
2
  pageId,
3
  instruction: "Extract all order line items and their quantities.",
4
}, { runtimeId: runtime.id });
5
6
const result = await bctrl.toolCalls.result(call.id, {
7
  waitSeconds: 120,
8
});

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

Next

• Stagehand observe — find elements first
• Stagehand act — perform a browser action
• AI models — choose the model used by the Agent environment