Automation Events

The /v1/automate endpoint streams responses using Server-Sent Events (SSE). Each event follows this format:

event: <type>
data: <JSON>

This reference documents all event types, their data structures, and when they are emitted.

---

Task Events

start

Emitted when the task is initialized.

{
  task: string;    // Task description
  url: string;     // Target URL
}

task:setup

Emitted during the task configuration and setup phase. No data payload.

task:started

Emitted when task execution begins.

{
  task: string;    // Task description
  url: string;     // Target URL
}

task:completed

Emitted when the task finishes successfully.

{
  success: true;
  finalAnswer: string;   // Human-readable result summary
}

task:aborted

Emitted when the task is terminated early. No data payload.

task:validated

Emitted when task completion validation passes. No data payload.

task:validation_error

Emitted when validation fails. No data payload.

---

Agent Events

agent:processing

Emitted when the agent is thinking or planning.

{
  operation: string;      // e.g., "Creating task plan", "Analyzing page content"
  hasScreenshot: boolean; // Whether a screenshot is being analyzed
}

agent:status

Emitted for status updates and plans.

{
  message: string;   // Status message, e.g., "Task plan created"
  plan: string;      // Description of the plan
}

agent:step

Emitted for processing step iterations.

{
  iterationId: string;    // Unique iteration identifier
  currentIteration: number; // Current step number (0-indexed)
}

agent:action

Emitted when actions are being performed.

{
  action: string;   // Action type, e.g., "extract"
  value: string;    // Action description
}

agent:reasoned

Emitted for agent reasoning output. No data payload.

agent:extracted

Emitted when data extraction completes.

{
  extractedData: string;  // JSON string of extracted data
}

agent:waiting

Emitted when the agent is waiting for operations to complete. No data payload.

---

Browser Events

browser:navigated

Emitted when page navigation occurs.

{
  title: string;   // Page title
  url: string;     // Current URL
}

browser:action_started

Emitted when a browser action is initiated. No data payload.

browser:action_completed

Emitted when a browser action finishes. No data payload.

browser:screenshot_captured

Emitted when a screenshot is taken. No data payload.

---

Interactive Events

These events are only emitted when interactive: true is set on the automate request. See the Interactive Mode guide for full usage details.

interactive:form_data:request

Emitted when the agent encounters a form requiring user data and needs input from the caller.

{
  requestId: string;        // Unique ID for this request (use when submitting response)
  pageUrl: string;          // URL of the page containing the form
  pageTitle: string;        // Page title
  formDescription: string;  // Human-readable description of the form
  fields: Array<{
    ref: string;            // Element reference ID (e.g., "E42")
    label: string;          // Field's visible label
    fieldType: string;      // "text" | "email" | "phone" | "date" | "number" | "select" | "checkbox" | "radio" | "textarea" | "password" | "other"
    required: boolean;      // Whether the field must be filled
    options?: string[];     // Available options (for select/radio fields)
    currentValue?: string;  // Current value if already partially filled
    description?: string;   // Additional context or hints
  }>;
}

Respond by submitting field values to POST /v1/automate/{requestId}/input. Input requests expire after 2 minutes.

interactive:form_data:error

Emitted when form submission fails validation after user-provided data was entered. Contains the same structure as interactive:form_data:request, plus per-field error details.

{
  requestId: string;
  pageUrl: string;
  pageTitle: string;
  formDescription: string;
  fields: Array<{
    ref: string;
    label: string;
    fieldType: string;
    required: boolean;
    options?: string[];
    currentValue?: string;
    description?: string;   // May contain the validation error message
  }>;
  fieldErrors: Record<string, string>;  // Map of ref -> error message (e.g., { "E42": "Invalid email address" })
}

Handle this the same way as the initial request: collect corrected values and submit them to the input endpoint using the new requestId.

---

System Events

system:debug_compression

Emitted for debug compression information. Used for internal diagnostics.

system:debug_message

Emitted for debug messages. Used for internal diagnostics.

---

Stream Control Events

complete

Emitted at the end of the stream with final results.

{
  success: boolean;
  result: {
    finalAnswer: string;   // Human-readable result
  };
  stats: {
    actions: number;       // Total number of actions performed
  };
}

done

Emitted as the stream termination signal.

{}

error

Emitted when an error occurs during task execution.

{
  error: string;    // Error message
  code?: string;    // Error code (if available)
}