### Start a Workflow Task

Source: https://docs.browseract.com/workflow/api-reference/tasks/run-a-workflow-create-a-task

Use this example to start a basic workflow task with a specified workflow ID and input parameters.

```json
{
  "workflow_id": "wf_123456789",
  "input_parameters": [
    {
      "name": "keyword",
      "value": "laptops"
    }
  ]
}
```

--------------------------------

### Start Workflow Task with Webhooks and Data Saving

Source: https://docs.browseract.com/workflow/api-reference/tasks/run-a-workflow-create-a-task

This example demonstrates how to start a workflow task, save browser data for reuse, and configure webhook URLs for notifications on task completion and status changes.

```json
{
  "workflow_id": "wf_123456789",
  "input_parameters": [
    {
      "name": "keyword",
      "value": "laptops"
    }
  ],
  "save_browser_data": true,
  "callback_url": "https://your-server.com/webhooks/workflow-callback",
  "status_change_callback_url": "https://your-server.com/webhooks/task-status-change-callback"
}
```

--------------------------------

### Install Browser-act Entry Skill

Source: https://docs.browseract.com/agent-cli/skill-system

Use this command to install the Browser-act Skill. After installation, the agent can recognize Browser-act tasks and call `get-skills` before using the CLI.

```text
Install the browser-act Skill from:
https://github.com/browser-act/skills/tree/main/browser-act
```

--------------------------------

### Install Skill Forge

Source: https://docs.browseract.com/agent-cli/skill-forge

Install the browser-act-skill-forge using the provided command. After installation, verify its availability.

```text
Install browser-act-skill-forge.
Skill URL: https://github.com/browser-act/skills/tree/main/browser-act-skill-forge
After installation, verify that it is available.
```

--------------------------------

### Agent-based Browser-act Installation

Source: https://docs.browseract.com/agent-cli/installation

Instruct an agent to install Browser-act by providing the installation command and the Skill URL. This method is suitable for agents that support skills.

```text
Install browser-act.
Skill URL: https://github.com/browser-act/skills/tree/main/browser-act
After installation, verify that the CLI is available.
```

--------------------------------

### Agent Confirmation Prompt Example

Source: https://docs.browseract.com/agent-cli/designed-for-agents

This example demonstrates how an agent should prompt the user for confirmation before performing a sensitive operation, specifying the details of the planned action.

```text
Agent: I plan to create a stealth browser for price monitoring.
       Type: stealth
       Name: price-monitor
       Proxy: US dynamic proxy

       Continue?

User: Yes.

Agent: Running browser create.
```

--------------------------------

### Browser State Example

Source: https://docs.browseract.com/agent-cli/quick-start

An example of the 'state' output, showing the current URL, title, and indexed elements on a login page.

```text
url=https://example.com/login
title=Login

*[1]<div id=login-form />
  *[2]<input type=email placeholder=Email address />
  *[3]<input type=password placeholder=Password />
  *[4]<button id=submit />
    Sign In
  *[5]<a />
    Forgot password?
```

--------------------------------

### Verify CLI Installation

Source: https://docs.browseract.com/agent-cli/installation

Check if the Browser-act CLI has been installed correctly by running the version command. This confirms the CLI is accessible in your environment.

```bash
browser-act --version
```

--------------------------------

### Manual CLI Installation with uv

Source: https://docs.browseract.com/agent-cli/installation

Install the Browser-act CLI using the `uv` tool with Python 3.12. This is a direct method for users managing their Python environments.

```bash
uv tool install browser-act-cli --python 3.12
```

--------------------------------

### Compact State Output Example

Source: https://docs.browseract.com/agent-cli/designed-for-agents

This is an example of the compact state output provided by Browser-act. The '*' marker indicates new or changed elements, helping agents focus on recent updates. Elements are indexed for command targeting.

```text
url=https://example.com/login
title=Login

*[1]<div id=login-form />
  *[2]<input type=email placeholder=Email address />
  *[3]<input type=password placeholder=Password />
  *[4]<button id=submit />
    Sign In
```

--------------------------------

### Generate Skill with Parameters

Source: https://docs.browseract.com/agent-cli/skill-forge

Generate a skill package using CLI parameters for business variables. This example shows how to search for jobs with specific keywords, location, and limit.

```bash
job-search --keyword "designer" --location "Berlin" --limit 100
```

--------------------------------

### Define Input Parameters for Scraper

Source: https://docs.browseract.com/workflow/learn/quick-start/build-your-first-data-scraper-workflow-in-5-minutes

Set up input parameters for 'Country' and 'Area' in the Start node. These values will be used later in the workflow for dynamic searching.

```text
Name: Country | Default Value: USA
Name: Area | Default Value:: Avalon, CA
```

--------------------------------

### Run an official workflow template (create a task)

Source: https://docs.browseract.com/workflow/api-reference/tasks/run-an-official-workflow-template-create-a-task

Starts a new task execution from an official workflow template and returns a `task_id`.

```APIDOC
## POST /v2/workflow/run-task-by-template

### Description
Starts a new task execution from an **official workflow template** and returns a `task_id`.

### Method
POST

### Endpoint
/v2/workflow/run-task-by-template

### Parameters
#### Request Body
- **template_name** (string) - Required - The name of the official workflow template to use.
- **input** (object) - Optional - The input parameters for the workflow template. Refer to the template's documentation for required and optional fields.
- **callback_url** (string) - Optional - A URL to receive webhook notifications when the task completes or fails.
- **status_change_callback_url** (string) - Optional - A URL to receive webhook notifications on any status change of the task.

### Response
#### Success Response (200)
- **task_id** (string) - The unique identifier for the newly created task.
- **status** (string) - The initial status of the task (e.g., "created" or "running").
```

--------------------------------

### Run a workflow (create a task)

Source: https://docs.browseract.com/llms.txt

Starts a new task execution for a workflow and returns a task ID.

```APIDOC
## POST /workflow/api-reference/tasks/run-a-workflow-create-a-task

### Description
Starts a new task execution for a workflow and returns a `task_id`.

### Method
POST

### Endpoint
/workflow/api-reference/tasks/run-a-workflow-create-a-task

### Parameters
#### Request Body
- **workflow_id** (string) - Required - The ID of the workflow to run.
- **inputs** (object) - Optional - Input parameters for the workflow.
```

--------------------------------

### Browser-act API Key Login Flow

Source: https://docs.browseract.com/agent-cli/installation

Initiate the login process for Browser-act API key authentication. This involves starting the login flow and then polling for completion.

```bash
browser-act auth login
browser-act auth poll
```

--------------------------------

### Check uv Tool Directory

Source: https://docs.browseract.com/agent-cli/installation

Display the directory where `uv` installs tools. This is useful for troubleshooting 'command not found' errors by ensuring this directory is in your system's PATH.

```bash
uv tool dir
```

--------------------------------

### Input Search Query Using Parameters

Source: https://docs.browseract.com/workflow/learn/quick-start/build-your-first-data-scraper-workflow-in-5-minutes

Use the 'Input Text' node to enter a search query into the target element. This example dynamically uses 'Country' and 'Area' parameters to form the search term.

```text
Country Area
```

--------------------------------

### Run a workflow (create a task)

Source: https://docs.browseract.com/workflow/api-reference/tasks/run-a-workflow-create-a-task

Starts a new task execution for a workflow and returns a `task_id`. You can provide input parameters, enable browser data saving, and configure webhooks for notifications.

```APIDOC
## POST /v2/workflow/run-task

### Description
Starts a new task execution for a workflow and returns a `task_id`.

### Method
POST

### Endpoint
/v2/workflow/run-task

### Parameters
#### Request Body
- **workflow_id** (string) - Required - The ID of the workflow to run.
- **input_parameters** (object) - Optional - Any input parameters required by the workflow.
- **save_browser_data** (boolean) - Optional - If true, browser data will be saved and a `profile_id` will be returned.
- **callback_url** (string) - Optional - A URL to receive POST notifications when the task finishes, fails, or is canceled.
- **status_change_callback_url** (string) - Optional - A URL to receive POST notifications whenever the task status changes.

### Response
#### Success Response (200)
- **task_id** (string) - The ID of the created task.
- **profile_id** (string) - Returned if `save_browser_data` is true. The ID of the saved browser profile.

#### Response Example
```json
{
  "task_id": "task_abc123",
  "profile_id": "profile_xyz789" 
}
```
```

--------------------------------

### Open a Browser Instance

Source: https://docs.browseract.com/

Opens a specified browser instance for a given task session and navigates to a URL.

```bash
browser-act --session my-task browser open <browser-id> https://example.com
```

--------------------------------

### Create a Standard Browser with Static Proxy

Source: https://docs.browseract.com/workflow/help/browser-configuration/how-to-use-browseract-proxies

Use this command to create a new browser instance bound to a specific static proxy. This is suitable for account management and long-lived sessions.

```bash
browser-act browser create --type stealth --name "<browser-name>" --desc "<browser-description>" --static-proxy <static-proxy-id>
```

--------------------------------

### Create Chrome Browser from Profile

Source: https://docs.browseract.com/agent-cli/browser-modes

Create a new isolated Chrome browser instance by importing state from a discovered local profile. Specify the type, a name, a description, and the source profile ID.

```bash
browser-act browser create \
  --type chrome \
  --name "work-account" \
  --desc "Logged-in work account for reporting" \
  --source-profile <profile_id>
```

--------------------------------

### Retrieve Task Information

Source: https://docs.browseract.com/workflow/api-reference/tasks/retrieve-a-task

Use this endpoint to get detailed information about a task, including its current status, step-by-step progress, and any output or failure details. If only the status is needed, consider using GET /v2/workflow/get-task-status.

```yaml
openapi: 3.1.0
info:
  title: BrowserAct API
  version: v2
  description: >
    BrowserAct's API lets you run BrowserAct workflows programmatically and
    monitor their execution.


    **Core concepts (same as the Dashboard):**

    - **Workflow**: a reusable automation blueprint (the "design").

    - **Task**: a single execution record of a workflow (the "run").


    ## Base URL

    All requests use the following base URL:

    ```

    https://api.browseract.com

    ```


    ## API versioning

    The API is versioned in the URL path (for example, `/v2/...`).


    ## Authentication

    Authenticate with a Bearer token in the `Authorization` header:

    ```

    Authorization: Bearer <API_KEY>

    ```


    ## Requests

    - Send request bodies as JSON.

    - Set `Content-Type: application/json` for endpoints that accept a body.


    ## Response codes

    We use standard HTTP status codes:

    - `2xx` for successful requests

    - `4xx` for client-side errors (invalid parameters, missing auth, etc.)

    - `5xx` for server-side errors


    ## Errors

    For most error responses, the API returns a standard JSON envelope:

    - `code`: non-zero means an error

    - `msg`: human-readable error message

    - `traceId`: include this when contacting support


    ## Pagination

    List endpoints use **page-based pagination** with these query parameters:

    - `page` (starts at 1)

    - `limit` (1-500)


    Paginated responses include: `page`, `limit`, `items`, `total_pages`,
    `total_count`.


    ## Webhooks (optional)

    When creating a task, you can provide:

    - `callback_url`: called when a task **finishes**, **fails**, or is
    **canceled**.

    - `status_change_callback_url`: called whenever the task status changes
    (e.g. running -> paused -> running).


    ## Task status values

    `created`, `running`, `finished`, `canceled`, `pausing`, `paused`, `failed`,
    `unknown`.


    ## Rate limits

    To protect platform stability, rate limits may apply. If you hit a limit,
    reduce request frequency and retry with backoff.


    ## Need help?

    Join our Discord community: https://discord.com/invite/UpnCKd7GaU
info:
  contact:
    name: BrowserAct Support
    url: https://discord.com/invite/UpnCKd7GaU
servers:
  - url: https://api.browseract.com
    description: Production
security:
  - HTTPBearer: []
tags:
  - name: Tasks
    description: |
      Create and manage **tasks** (executions).

      Typical flow:
      1) Start a task (`run-task` or `run-task-by-template`)
      2) Poll for status (`get-task-status`) or full details (`get-task`)
      3) Retrieve outputs from the task response once finished
  - name: Workflows
    description: >-
      Workflows are reusable automation blueprints created in the BrowserAct
      Dashboard.

      Use these endpoints to list workflows and fetch a workflow's expected
      input parameters.
  - name: Workflow Templates
    description: >-
      Official workflow templates curated by BrowserAct.

      Templates are a fast way to start with common scraping/automation use
      cases.
  - name: Regions
    description: >-
      Supported proxy regions that can be used when running template-based
      tasks.
paths:
  /v2/workflow/get-task:
    get:
      tags:
        - Tasks
      summary: Retrieve a task
      description: >-
        Returns comprehensive information about a task, including:

        - current `status`

        - step-level progress (`steps`)

        - output (if finished)

        - failure details (if failed)

```

--------------------------------

### Interacting with Page Elements

Source: https://docs.browseract.com/agent-cli/quick-start

Demonstrates how to use element indexes obtained from the 'state' command to input text and click buttons.

```bash
browser-act --session login input 2 "user@example.com"
browser-act --session login input 3 "password123"
browser-act --session login click 4
```

--------------------------------

### Get Browser State

Source: https://docs.browseract.com/

Retrieves the current state of the browser for a specific task session.

```bash
browser-act --session my-task state
```

--------------------------------

### Get Task Status

Source: https://docs.browseract.com/workflow/api-reference/tasks/retrieve-a-task-status

Retrieves the current status of a specified task. This is a lightweight endpoint useful for polling task progress.

```APIDOC
## GET /v2/workflow/get-task-status

### Description
This endpoint is more lightweight than `GET /v2/workflow/get-task`.

### Method
GET

### Endpoint
/v2/workflow/get-task-status

### Parameters
#### Query Parameters
- **task_id** (string) - Required - Task ID returned by `run-task` or `run-task-by-template`.

### Response
#### Success Response (200)
- **status** (TaskStatus) - Description of the task status.

#### Response Example
```json
{
  "status": "running"
}
```

#### Error Response (400)
- **code** (integer) - Response code. `0` means success; non-zero means failure.
- **msg** (string) - Human-readable error message (present when `code` is non-zero).
- **data** (object) - Error details (shape may vary by error).
- **ts** (integer) - Server timestamp (milliseconds).
- **time** (string) - Server time in ISO 8601 format.
- **traceId** (string) - Error ID for tracking in logs.

#### Error Response (500)
- **code** (integer) - Response code. `0` means success; non-zero means failure.
- **msg** (string) - Human-readable error message (present when `code` is non-zero).
- **data** (object) - Error details (shape may vary by error).
- **ts** (integer) - Server timestamp (milliseconds).
- **time** (string) - Server time in ISO 8601 format.
- **traceId** (string) - Error ID for tracking in logs.
```

--------------------------------

### Create a New Browser Instance

Source: https://docs.browseract.com/agent-cli/command-reference

Creates a new browser instance with specified type, name, and description. Various options are available for configuring proxies, source profiles, and privacy settings.

```bash
browser-act browser create \
  --type chrome|chrome-direct|stealth \
  --name "my-browser" \
  --desc "Purpose description" \
  --source-profile <profile_id> \
  --dynamic-proxy <region> \
  --custom-proxy <url> \
  --private true|false \
  --confirm-before-use
```

--------------------------------

### Browser Automation Workflow

Source: https://docs.browseract.com/agent-cli/quick-start

This sequence demonstrates the typical workflow for automating browser tasks, from listing available browsers to closing a session.

```bash
# 1. List available browsers
browser-act browser list

# 2. Open a browser and start a named session
browser-act --session my-task browser open <browser_id> https://example.com

# 3. Read the current page state
browser-act --session my-task state

# 4. Interact with elements by index
browser-act --session my-task click 4
browser-act --session my-task input 2 "hello@example.com"

# 5. Close the session when finished
browser-act session close my-task
```

--------------------------------

### Run Workflow Template Task

Source: https://docs.browseract.com/workflow/api-reference/tasks/run-an-official-workflow-template-create-a-task

Initiates a new task by running an official workflow template. You can discover available templates using `GET /v2/workflow/list-official-workflow-templates`.

```APIDOC
## POST /v2/workflow/run-official-workflow-template

### Description
Starts a new task from an official workflow template.

### Method
POST

### Endpoint
/v2/workflow/run-official-workflow-template

### Parameters
#### Request Body
- **workflow_template_id** (string) - Required - The official workflow template ID to run.
- **proxyRegion** (string) - Optional - Proxy region code. Defaults to `US`.
- **input_parameters** (array) - Optional - Input parameters for this run.
  - **name** (string) - Required - Parameter name.
  - **value** (string) - Required - Parameter value as a string.
- **callback_url** (string) - Optional - URL to receive callback notifications.
- **status_change_callback_url** (string) - Optional - URL to receive status change notifications.

### Request Example
```json
{
  "proxyRegion": "US",
  "workflow_template_id": "tpl_123456789",
  "input_parameters": [
    {
      "name": "url",
      "value": "https://example.com"
    }
  ]
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique `task_id`.
- **profile_id** (string) - Returned only when `save_browser_data` is `true`. Use it to reuse browser data.

#### Response Example
```json
{
  "id": "task_123456789",
  "profile_id": "profile_abc123"
}
```
```

--------------------------------

### List Available Browsers

Source: https://docs.browseract.com/agent-cli/command-reference

Lists all available browser instances managed by the agent. No session is required.

```text
browser list
```

--------------------------------

### Retrieve a Workflow

Source: https://docs.browseract.com/workflow/api-reference/workflows/retrieve-a-workflow

Fetches a workflow’s configuration, including the input parameter definitions needed to run it. If you only need a list of workflows, use `GET /v2/workflow/list-workflows`.

```APIDOC
## GET /v2/workflow/get-workflow

### Description
Fetches a workflow’s configuration, including the input parameter definitions needed to run it.

### Method
GET

### Endpoint
/v2/workflow/get-workflow

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Send your API key in the `Authorization` header as `Bearer <API_KEY>`.

#### Query Parameters
- **workflow_id** (string) - Required - Workflow ID.

### Response
#### Success Response (200)
- **id** (string) - Workflow ID
- **name** (string) - Workflow name
- **description** (string) - Workflow description
- **create_at** (string<date-time>) - Workflow creation time
- **publish_at** (string<date-time>) - Workflow publish time
- **input_parameters** (object[]) - Input parameters required to run this workflow.

### Response Example
```json
{
  "id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "create_at": "2023-11-07T05:31:56Z",
  "publish_at": "2023-11-07T05:31:56Z",
  "input_parameters": [
    {
      "name": "keyword",
      "default_enabled": true
    }
  ]
}
```
```

--------------------------------

### Retrieve a Workflow

Source: https://docs.browseract.com/workflow/api-reference/workflows/retrieve-a-workflow

Use this cURL command to make a GET request to retrieve a workflow's configuration. Ensure you replace `<token>` with your actual API key.

```curl
curl --request GET \
  --url https://api.browseract.com/v2/workflow/get-workflow \
  --header 'Authorization: Bearer <token>'
```

--------------------------------

### Configure Output as CSV File

Source: https://docs.browseract.com/workflow/learn/quick-start/build-your-first-data-scraper-workflow-in-5-minutes

Set up the 'Finish: Output Data' node to export the scraped data. Specify 'CSV' as the output format and enable 'Output as a file' for direct download.

```text
Output Format: CSV
Enable: “Output as a file”
```

--------------------------------

### Get Core Skills with Specific Version

Source: https://docs.browseract.com/agent-cli/skill-system

Use the `--skill-version` parameter to detect version mismatches. This command retrieves core skills for a specific version.

```bash
browser-act get-skills core --skill-version 2.0.2
```

--------------------------------

### List Available Browsers

Source: https://docs.browseract.com/

Command to list all available browser instances that can be controlled by Browser-act.

```bash
browser-act browser list
```

--------------------------------

### Send Browser-act Feedback

Source: https://docs.browseract.com/agent-cli/installation

Submit product feedback or describe an issue directly through the CLI. Replace 'Describe the issue or suggestion' with your specific feedback.

```bash
browser-act feedback "Describe the issue or suggestion"
```

--------------------------------

### Save Extracted Page Content to File

Source: https://docs.browseract.com/agent-cli/quick-start

Use the `--output` option with `stealth-extract` to save the fetched page content directly to a specified file, for example, `./page.md`.

```bash
browser-act stealth-extract https://example.com --output ./page.md
```

--------------------------------

### Open a Browser Instance or URL

Source: https://docs.browseract.com/agent-cli/command-reference

Opens a specified browser instance by its ID or launches a URL in a new browser. Options include running in headed mode, private mode, or allowing Chrome restarts.

```text
browser open <id_or_url> [url_arg] [--headed] [--private] [--allow-restart-chrome]
```