History Tracking

Track and analyze Stagehand operations with the history API

The history API captures every Stagehand operation for debugging, auditing, and workflow analysis.

Basic Usage

import { Stagehand } from "@browserbasehq/stagehand";

const stagehand = new Stagehand({ env: "BROWSERBASE" });
await stagehand.init();
const page = stagehand.context.pages()[0];

await page.goto("https://example.com");
await stagehand.act("click login button");

// Get complete history
const history = await stagehand.history;

console.log(`Total operations: ${history.length}`);
history.forEach((entry, i) => {
  console.log(`${i + 1}. ${entry.method} at ${entry.timestamp}`);
});

await stagehand.close();

History Entry Structure

interface HistoryEntry {
  method: "act" | "extract" | "observe" | "navigate" | "agent";
  parameters: unknown;  // Input parameters
  result: unknown;      // Output/result
  timestamp: string;    // ISO 8601 timestamp
}

Common Use Cases

Debugging Failures

try {
  await stagehand.act("click login button");
} catch (error) {
  const history = await stagehand.history;

  history.forEach((entry, i) => {
    const status = entry.result && 'error' in entry.result ? "FAILED" : "SUCCESS";
    console.log(`${i + 1}. ${status} - ${entry.method}`);
  });
}

Analyzing Timing

const history = await stagehand.history;

const timings = history.map((entry, i) => {
  if (i === 0) return null;
  const duration = new Date(entry.timestamp).getTime() -
                   new Date(history[i - 1].timestamp).getTime();
  return { operation: entry.method, duration };
}).filter(Boolean);

console.log("Slowest operations:",
  timings.sort((a, b) => b.duration - a.duration).slice(0, 3)
);

Operation Statistics

const history = await stagehand.history;

const stats = history.reduce((acc, entry) => {
  acc[entry.method] = (acc[entry.method] || 0) + 1;
  return acc;
}, {} as Record<string, number>);

console.log("Operations:", stats);
// { act: 5, extract: 2, observe: 3, navigate: 1 }

Saving History

import fs from "fs/promises";

const history = await stagehand.history;
const metrics = await stagehand.metrics;

await fs.writeFile(
  `workflow-report.json`,
  JSON.stringify({
    history,
    totalOps: history.length,
    totalTokens: metrics.totalPromptTokens + metrics.totalCompletionTokens
  }, null, 2)
);

Filtering by Operation Type

const history = await stagehand.history;

const actions = history.filter(e => e.method === 'act');
const extractions = history.filter(e => e.method === 'extract');
const agentOps = history.filter(e => e.method === 'agent');

console.log(`Actions: ${actions.length}`);
console.log(`Extractions: ${extractions.length}`);
console.log(`Agent executions: ${agentOps.length}`);

Combining with Metrics

const history = await stagehand.history;
const metrics = await stagehand.metrics;

const report = {
  totalOps: history.length,
  successful: history.filter(e => !e.result || !('error' in e.result)).length,
  failed: history.filter(e => e.result && 'error' in e.result).length,
  totalTokens: metrics.totalPromptTokens + metrics.totalCompletionTokens,
  avgTimePerOp: `${(metrics.totalInferenceTimeMs / history.length).toFixed(0)}ms`
};

console.log(report);

Observability Guide

Learn more about metrics, logging, and monitoring

What’s Tracked?

Only Stagehand methods are tracked in history:

// Tracked
await stagehand.act("click button");              // ✓
await stagehand.extract({ instruction: "..." }); // ✓
await stagehand.observe("find elements");         // ✓
await page.goto("https://example.com");      // ✓

// Not tracked
await page.locator("button").click();        // ✗ Native Playwright
await page.click("button");                  // ✗ Native Playwright

Best Practices

• Save history for critical workflows - Maintain audit trails for production
• Inspect history when debugging - Check the last operations to identify failures
• Analyze timing periodically - Find slow operations and optimize
• Combine with metrics - Get complete visibility into performance and cost

Next Steps

Deterministic Agent

Build fast, cached agent workflows

Observability

Combine history with metrics

Caching

Speed up workflows with caching

Logging

Configure detailed execution traces