---
title: Understanding Automate Event Flow | Tabstack
description: When you call the `/v1/automate` endpoint, the API streams real-time updates about task execution through Server-Sent Events (SSE). This guide explains how events flow during a typical automation task and how to use them effectively in your application.
---

## How Event Streaming Works

The automate endpoint establishes a persistent connection and streams events as the task progresses. Each event represents a distinct phase or action in the automation lifecycle. Your client receives these events in real-time, allowing you to:

- Display progress updates to users
- Track the current state of the task
- Capture extracted data as it becomes available
- Handle errors gracefully

## The Event Lifecycle

A typical automation task flows through these phases:

### 1. Initialization

When you submit a request, the first events establish the task context:

```
event: start
data: {"task": "Find the product price", "url": "https://example.com/product"}


event: task:setup
data: {}


event: task:started
data: {"task": "Find the product price", "url": "https://example.com/product"}
```

At this point, your client knows the task has been accepted and the browser is being prepared. You might display a “Starting task…” message to the user.

### 2. Planning and Processing

The agent analyzes the page and creates an execution plan:

```
event: agent:processing
data: {"operation": "Creating task plan", "hasScreenshot": true}


event: agent:status
data: {"message": "Task plan created", "plan": "1. Navigate to product page\n2. Locate price element\n3. Extract price value"}
```

The `agent:processing` event fires whenever the agent is thinking. The `hasScreenshot` field indicates whether the agent is analyzing visual content. Use this to show a “Thinking…” or “Analyzing page…” indicator.

The `agent:status` event provides the plan in human-readable format. You can display this to give users visibility into what the automation will do.

### 3. Execution Steps

As the agent executes the plan, it emits events for each step:

```
event: agent:step
data: {"iterationId": "abc123", "currentIteration": 0}


event: browser:navigated
data: {"title": "Product Details - Example Store", "url": "https://example.com/product/123"}


event: agent:action
data: {"action": "click", "value": "Clicking on price details button"}


event: browser:action_started
data: {}


event: browser:action_completed
data: {}
```

The `agent:step` event marks each iteration of the execution loop. Use `currentIteration` to show progress (e.g., “Step 1 of 5”).

Browser events tell you what’s happening in the automated browser:

- `browser:navigated` - The page URL or title changed
- `browser:action_started` / `browser:action_completed` - An interaction (click, type, scroll) is in progress

### 4. Data Extraction

When the agent extracts data from the page, you receive it immediately:

```
event: agent:action
data: {"action": "extract", "value": "Extracting product price"}


event: agent:extracted
data: {"extractedData": "{\"price\": \"$29.99\", \"currency\": \"USD\"}"}
```

The `extractedData` field contains a JSON string. Parse it to access the structured data:

```
eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (event.type === "agent:extracted") {
    const extracted = JSON.parse(data.extractedData);
    console.log("Price:", extracted.price); // "$29.99"
  }
};
```

You may receive multiple `agent:extracted` events if the task involves extracting data from different pages or elements.

### 5. Completion

When the task finishes successfully:

```
event: task:validated
data: {}


event: task:completed
data: {"success": true, "finalAnswer": "The product price is $29.99 USD"}


event: complete
data: {"success": true, "result": {"finalAnswer": "The product price is $29.99 USD"}, "stats": {"actions": 5}}


event: done
data: {}
```

The `task:completed` and `complete` events both indicate success, but serve different purposes:

- `task:completed` - The automation logic finished successfully
- `complete` - The final summary with statistics about the run

The `done` event signals the end of the stream. Close your EventSource connection when you receive this.

## Handling Errors

If something goes wrong during execution:

```
event: error
data: {"error": "Unable to locate element", "code": "ELEMENT_NOT_FOUND"}
```

Errors can occur at any point. Your client should always have an error handler ready:

```
eventSource.addEventListener("error", (event) => {
  const data = JSON.parse(event.data);
  console.error("Task failed:", data.error);
  eventSource.close();
});
```

If a task is terminated early, you’ll receive:

```
event: task:aborted
data: {}
```

## Building a Client

Here’s a pattern for handling the event stream:

```
const eventSource = new EventSource("/v1/automate", {
  // Include auth headers via fetch or use withCredentials
});


const state = {
  status: "starting",
  plan: null,
  currentStep: 0,
  extractedData: [],
  result: null,
};


eventSource.addEventListener("task:started", (e) => {
  state.status = "running";
});


eventSource.addEventListener("agent:status", (e) => {
  const data = JSON.parse(e.data);
  state.plan = data.plan;
});


eventSource.addEventListener("agent:step", (e) => {
  const data = JSON.parse(e.data);
  state.currentStep = data.currentIteration + 1;
});


eventSource.addEventListener("agent:extracted", (e) => {
  const data = JSON.parse(e.data);
  state.extractedData.push(JSON.parse(data.extractedData));
});


eventSource.addEventListener("complete", (e) => {
  const data = JSON.parse(e.data);
  state.status = "completed";
  state.result = data.result;
});


eventSource.addEventListener("error", (e) => {
  state.status = "error";
  eventSource.close();
});


eventSource.addEventListener("done", () => {
  eventSource.close();
});
```

## Key Takeaways

- **Events stream in real-time** - Update your UI as events arrive rather than waiting for completion
- **Track state with `agent:step`** - Use `currentIteration` to show progress
- **Parse `extractedData` as JSON** - It’s a stringified JSON object
- **Always handle errors** - Tasks can fail at any point
- **Close on `done`** - The stream ends with the `done` event
- **Use `complete` for final results** - It contains the summary and statistics

For a complete list of all events and their data structures, see the [Automation Events Reference](/api/resources/automate/methods/execute/index.md).