Workflows (Beta)

Workflows are reusable automation sequences that can be generated once and executed multiple times with different inputs. Unlike tasks that require AI processing for every execution, workflows are deterministic YAML-based scripts that provide faster, more cost-effective automation.

When to Use Workflows

Use Workflows for:

• ✅ Repetitive tasks with similar structure
• ✅ Form submissions with variable data
• ✅ Data extraction from consistent page layouts
• ✅ Multi-user operations (same flow, different credentials)
• ✅ Scheduled automations

Use Tasks for:

• ❌ One-time or exploratory automation
• ❌ Dynamic, unpredictable scenarios
• ❌ Complex decision-making requirements

Quick Start

1. Create & Generate Workflow

Create a workflow and generate it from a task description in one flow:

$
# Step 1: Create workflow
>
WORKFLOW=$(curl -X POST "https://api.cloud.browser-use.com/v2/workflows" \
>
  -H "Authorization: Bearer $API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{"name": "Contact Form Submission"}')
>
>
WORKFLOW_ID=$(echo $WORKFLOW | jq -r '.id')
>
>
# Step 2: Generate from task description
>
curl -X POST "https://api.cloud.browser-use.com/v2/workflows/$WORKFLOW_ID/generate" \
>
  -H "Authorization: Bearer $API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "task_prompt": "Fill out contact form at example.com with name, email, and message"
>
  }'
>
>
# Step 3: Wait for generation to complete
>
while true; do
>
  STATUS=$(curl -s "https://api.cloud.browser-use.com/v2/workflows/$WORKFLOW_ID" \
>
    -H "Authorization: Bearer $API_KEY" | jq -r '.generation_status')
>
>
  if [ "$STATUS" = "completed" ]; then
>
    echo "✓ Workflow ready!"
>
    break
>
  elif [ "$STATUS" = "failed" ]; then
>
    echo "✗ Generation failed"
>
    exit 1
>
  fi
>
>
  sleep 3
>
done

Generation Cost: $0.01 per step

2. Execute with Inputs

Once generated, execute the workflow with different inputs:

$
curl -X POST "https://api.cloud.browser-use.com/v2/workflows/$WORKFLOW_ID/execute" \
>
  -H "Authorization: Bearer $API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "input": {
>
      "name": "John Doe",
>
      "email": "john@example.com",
>
      "message": "Hello!"
>
    }
>
  }'

Execution Cost: LLM tokens + $0.001 initialization

Generation Options

Variable Extraction

The system automatically detects input variables from your task prompt:

1
{
2
    "task_prompt": "Login with email: user@example.com and password: test123",
3
    "enable_variable_extraction": true,
4
    "enable_pattern_variable_identification": true,  // Free, pattern-based
5
    "pattern_variable_confidence": 0.5,              // 0.0-1.0
6
    "enable_ai_validation": false                    // Adds LLM cost
7
}

Variable Detection Methods:

YAML Cleanup

Optimize generated workflows for readability:

1
{
2
    "cleanup_yaml": true,
3
    "remove_descriptions": false,           // Keep step descriptions
4
    "remove_verification_checks": true,     // Remove validation steps
5
    "remove_expected_outcomes": true,
6
    "remove_agent_reasoning": true
7
}

Execution Management

Check Execution Status

$
curl "https://api.cloud.browser-use.com/v2/workflows/executions/$EXECUTION_ID" \
>
  -H "Authorization: Bearer $API_KEY"

Response:

1
{
2
    "id": "...",
3
    "status": "completed",
4
    "output": { /* extracted data */ },
5
    "llms_cost": 0.0025,
6
    "init_cost": 0.001
7
}

Cancel Execution

$
curl -X PATCH "https://api.cloud.browser-use.com/v2/workflows/executions/$EXECUTION_ID/cancel" \
>
  -H "Authorization: Bearer $API_KEY"

Get Execution Logs

$
curl "https://api.cloud.browser-use.com/v2/workflows/executions/$EXECUTION_ID/logs" \
>
  -H "Authorization: Bearer $API_KEY"

Returns a presigned URL to download detailed execution logs.

Workflow States

Generation Status

• pending - Created, generation not started
• generating - Recording browser interactions
• completed - Ready to execute
• failed - Generation error occurred

Execution Status

• pending - Queued for execution
• running - Currently executing
• completed - Finished successfully
• failed - Error during execution
• cancelled - Manually stopped

Best Practices

Task Prompts:

• ✓ Be specific: “Fill form at example.com/contact with name, email”
• ✓ Include example values: “name: John Doe, email: john@example.com”
• ✗ Avoid vague: “Submit the form”

Cost Optimization:

• Generate once, execute many times
• Use pattern-based variable detection (free)
• Enable AI validation only for complex scenarios
• Minimize extract_page_content steps in workflows

Monitoring:

• Use webhooks for production systems (see Webhooks)
• Implement exponential backoff for polling
• Download logs for failed executions

Input Validation:

• Check workflow’s input_schema before executing
• Use the input_template as a starting point
• Validate required parameters

Webhooks

Receive real-time notifications for workflow execution status changes:

1
{
2
    "type": "workflow.execution.status_changed",
3
    "data": {
4
        "execution_id": "...",
5
        "workflow_id": "...",
6
        "status": "completed",
7
        "output": { /* results */ }
8
    }
9
}

See Webhooks documentation for setup and signature verification.

Limitations (Beta)

• Sync execution mode not yet implemented (only async available)
• Generated workflows work best with consistent page structures
• Complex dynamic scenarios may require traditional tasks
• File uploads in workflows have limited support

API Reference

For complete API documentation including all parameters, response formats, and error codes, see: