Skip to main content

Observe

POST 
/workstations/:workstation_id/browser/operator/observe

Observe the current page and provide a detailed description of the page content. This endpoint can be used to make assertions about the page state or get detailed information about what is currently visible.

Key Features​

  • Natural language assertions about page content
  • Detailed page state descriptions
  • Visual element verification
  • Content validation
  • State checking

Example Usage​

// Make assertions about page content
const id = 'HvcqZjmeoPtP';
const url = `https://api.agentstation.ai/v1/workstations/${id}/browser/operator/observe`;
const response = await fetch(url, {
  method: 'POST',
  body: JSON.stringify({
    observation: 'The price of "Sauce Labs Onesie" is 7.99',
  })
});

Best Practices​

  1. Use specific assertions to verify exact values or states
  2. Include clear error messages for failed assertions
  3. Consider using extract endpoint for structured data validation
  4. Use observation mode for general page state analysis
  5. For critical assertions, combine with structured data extraction to prevent AI hallucinations: 
    // Instead of simple assertion:
    const response = await fetch(url, \{
      method: 'POST',
      body: JSON.stringify(\{
        assertion: 'The price of "Sauce Labs Onesie" is 7.99'
      \})
    \});
    // Response: \{ observation: true, message: "Found product 'Sauce Labs Onesie' with price $7.99 as expected" \}

    // More reliable approach using extract + JavaScript assertions:
    const url = `https://api.agentstation.ai/v1/workstations/${id}/browser/operator/extract`;
    const extractResponse = await fetch(url, \{
        method: 'POST',
        body: JSON.stringify(\{
          object: \{
            products: "product list with name and price, \{name: string, price: number\}[]"
          \}
        \})
      \}
    );
    const data = await extractResponse.json();
    // Response: \{ products: [\{ name: "Sauce Labs Onesie", price: 7.99 \}, ...] \}

    const onesieItem = data.products.find(item => item.name === 'Sauce Labs Onesie');
    if (!onesieItem) \{
      throw new Error('Sauce Labs Onesie not found');
    \}
    if (onesieItem.price !== 7.99) \{
      throw new Error(`Expected price 7.99 but got ${onesieItem.price}`);
    \}

Request​

Responses​

Successfully observed page content or validated assertion