Skip to navigation
AutomationToolsBuilt-in ToolsStagehand

Extract

View as Markdown

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

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

ParameterTypeRequiredDescription
instructionstringYesWhat to extract, from 1 to 20,000 characters.
pageIdPageIdNoPage to inspect. Uses the active page when omitted.
timeoutMsintegerNoMaximum extraction time in milliseconds. Maximum: 120000.
schemaJsonObjectNoJSON schema for the extracted value.

Response

FieldTypeAlways presentDescription
valueJsonValueYesValue extracted from the page.
cacheStatus"HIT" | "MISS"NoWhether 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

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