---
title: "AI Task"
method: POST
path: "/automate"
tags: ["Automate"]
---

# AI Task

`POST /automate`

Execute AI-powered browser automation tasks using natural language with optional geotargeting. This endpoint **always streams** responses using Server-Sent Events (SSE).

**Streaming Response:**
- All responses are streamed using Server-Sent Events (`text/event-stream`)
- Real-time progress updates and results as they're generated

**Geotargeting:**
- Optionally specify a country code for geotargeted browsing

**Use Cases:**
- Web scraping and data extraction
- Form filling and interaction
- Navigation and information gathering
- Multi-step web workflows
- Content analysis from web pages

## Request body

- V1AutomateRequest
  - `data` object — JSON data to provide context for form filling or complex tasks
  - `geo_target` GeotargetGeoTarget
    - `country` string — Country code using ISO 3166-1 alpha-2 standard (2 letters, e.g., "US", "GB", "JP"). See: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
  - `guardrails` string — Safety constraints for execution
  - `interactive` boolean — Enable interactive mode to allow human-in-the-loop input during task execution
  - `maxIterations` integer — Maximum task iterations
  - `maxValidationAttempts` integer — Maximum validation attempts
  - `task` string, required — The task description in natural language
  - `trusted_hostnames` string[] — TrustedHostnames lists hostnames where the action firewall is bypassed for fills and submissions. WARNING: on listed hosts, prompt injection from page content can drive the agent to fill and submit any field, including personal and credential data. Use only for sites you fully trust to receive your data.
  - `unsafe_mode` boolean — UnsafeMode disables the action firewall entirely. WARNING: prompt injection from page content can then cause the agent to submit your data, including credentials, personal information, and conversation context, to attacker-controlled forms. Only enable for trusted, controlled environments.
  - `url` string, uri — Starting URL for the task

## Response `200`

Task executed successfully (always streaming)

**Streaming Response using Server-Sent Events:**
All responses from the automate endpoint are streamed using Server-Sent Events.

**Event Format:**
- Each event starts with `event: <type>` followed by `data: <JSON>`
- Empty lines separate events

**Event Types:**

**Task Events:**
- `start`: Task initialization
- `task:setup`: Task configuration
- `task:started`: Task execution begins
- `task:completed`: Task finished successfully
- `task:aborted`: Task was terminated
- `task:validated`: Task completion validation
- `task:validation_error`: Validation failed

**Agent Events:**
- `agent:processing`: Agent thinking/planning
- `agent:status`: Status updates and plans
- `agent:step`: Processing step iterations
- `agent:action`: Actions being performed
- `agent:reasoned`: Agent reasoning output
- `agent:extracted`: Data extraction results
- `agent:waiting`: Agent waiting for operations

**Browser Events:**
- `browser:navigated`: Page navigation events
- `browser:action_started`: Browser action initiated
- `browser:action_completed`: Browser action finished
- `browser:screenshot_captured`: Screenshot taken

**System Events:**
- `system:debug_compression`: Debug compression info
- `system:debug_message`: Debug messages

**Stream Control:**
- `complete`: End of stream with results
- `done`: Stream termination
- `error`: Error occurred

## Other responses

- `400` — Bad request - Invalid task or missing required fields
- `401` — Unauthorized - Invalid or missing Bearer token
- `402` — Payment Required - organization is out of credits
- `429` — Too Many Requests - rate limit exceeded
- `500` — Internal server error
- `503` — Service unavailable - Automate service not configured

## Changes

> 8 revisions in range; 1 could not be searched.

- **2026-05-05** `1ccfa0fbdfeb` — 1 breaking, 1 info
  - added `#/components/schemas/v1.AutomateEvent_TaskTraceContext` to the response body `oneOf` list for the response status `200`
  - added `task:trace_context` mapping keys to the response discriminator for the response status `200`
- **2026-04-24** `5e6e6508dca1` — 1 breaking, 1 info
  - added `#/components/schemas/v1.AutomateEvent_Complete, #/components/schemas/v1.AutomateEvent_Done, #/components/schemas/v1.AutomateEvent_Error` to the response body `oneOf` list for the response status `200`
  - added `complete, done, error` mapping keys to the response discriminator for the response status `200`
- …earlier changes not shown

[Full history](https://skmtc.dev/mozilla-ocho/apis/tabs-api/changes/automate/post.md)

---

[API](https://skmtc.dev/mozilla-ocho/apis/tabs-api.md) · [All operations](https://skmtc.dev/mozilla-ocho/apis/tabs-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mozilla-ocho/tabs-api/revisions/f3f7ba7d83e4/schema)