Run browser automation synchronously

Execute a browser automation task synchronously and wait for completion. Returns the final result once the automation finishes (success or failure). Use this endpoint when you need the complete result in a single response. Note: Runs created via this endpoint cannot be cancelled. If you need cancellation support, use /v1/automation/run-async or /v1/automation/run-sse instead.

Request body

urlstring uri required

Target website URL to automate

goalstring required

Natural language description of what to accomplish on the website

browser_profile'lite' | 'stealth'

Browser profile for execution. LITE uses standard browser, STEALTH uses anti-detection browser.

api_integrationstring

Name of the integration making this API call (e.g., "dify", "zapier", "n8n"). Used for analytics.

webhook_urlstring uri

HTTPS URL to receive webhook notifications for run lifecycle events. Must use HTTPS.

use_vaultboolean

Opt-in to vault credentials for this run. When true, enabled vault items are included. Defaults to false.

use_profileboolean

Opt-in to the default Browser Context Profile if Browser Context Profiles are enabled; legacy callers are silently ignored when the profiles feature is disabled. Returns 400 when enabled but no default profile is set.

profile_idstring

Browser Context Profile ID to use when use_profile is true.

credential_item_idsstring[]

Scope vault credentials to specific credential URIs. Requires use_vault to be true. If omitted with use_vault: true, all enabled items are used.

output_schemaobject

Optional provider-supported structured-output schema subset for the run result. Unsupported fields are rejected before the request is accepted.

Example request

{
  "url": "https://example.com",
  "goal": "Find the pricing page and extract all plan details",
  "browser_profile": "lite",
  "api_integration": "dify",
  "agent_config": {
    "mode": "strict",
    "cursor_style": "standard",
    "max_steps": 50,
    "max_duration_seconds": 300
  },
  "use_vault": true,
  "use_profile": true,
  "profile_id": "prof_abc123def4567890",
  "credential_item_ids": [
    "cred:conn-abc:Work:item-123",
    "cred:conn-def:Personal:item-456"
  ],
  "proxy_config": {
    "enabled": true,
    "country_code": "US"
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string"
      },
      "price": {
        "type": "number"
      }
    },
    "required": [
      "title",
      "price"
    ]
  }
}

Response

Automation completed successfully. Returns run details and the extracted result.

run_idstring nullable required

Unique identifier for the automation run

status'COMPLETED' | 'FAILED' required

Final status of the automation run

started_atstring nullable required

ISO 8601 timestamp when the run started

finished_atstring nullable required

ISO 8601 timestamp when the run finished

num_of_stepsnumber nullable required

Number of steps taken during the automation. Null while the run is still in progress.

resultobject nullable required

Structured JSON result extracted from the automation. Null if the run failed.

Example response

{
  "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "COMPLETED",
  "started_at": "2024-01-01T00:00:00Z",
  "finished_at": "2024-01-01T00:00:30Z",
  "num_of_steps": 5,
  "result": {
    "product": "iPhone 15",
    "price": "$799"
  },
  "error": {
    "code": "service_busy",
    "message": "Browser crashed during execution",
    "category": "SYSTEM_FAILURE",
    "retry_after": 60,
    "help_url": "https://docs.tinyfish.ai/prompting-guide",
    "help_message": "Need help? Check out our goal prompting guide for tips and examples.",
    "profile_hint": {
      "setup_url": "/profiles/prof_abc123/setup?domain=example.com&returnTo=%2Fruns%2Frun_123&ref=run_error_nudge",
      "reason": "auth_wall"
    }
  },
  "profile_hint": {
    "setup_url": "/profiles/prof_abc123/setup?domain=example.com&returnTo=%2Fruns%2Frun_123&ref=run_error_nudge",
    "reason": "auth_wall"
  }
}