---
title: "Run browser automation synchronously"
method: POST
path: "/v1/automation/run"
tags: ["Automation"]
---

# Run browser automation synchronously

`POST /v1/automation/run`

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

- object
  - `url` string, uri, required — Target website URL to automate
  - `goal` string, 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_integration` string — Name of the integration making this API call (e.g., "dify", "zapier", "n8n"). Used for analytics.
  - `agent_config` object — Agent behavior configuration
    - `mode` 'default' | 'strict' — Agent behavior mode. "strict" enables fail-fast for test automation.
    - `cursor_style` 'fish' | 'standard' | 'green-pointer' — Cursor style for the browser agent.
    - `max_steps` integer — Maximum tool-call steps before the agent stops. Defaults to 150.
    - `max_duration_seconds` integer — Maximum wall-clock seconds before the agent stops. Defaults to no limit.
  - `capture_config` object — Configure which data to capture during the run.
    - `elements` boolean
    - `snapshots` boolean
    - `screenshots` boolean
    - `recording` boolean
    - `html` boolean
  - `webhook_url` string, uri — HTTPS URL to receive webhook notifications for run lifecycle events. Must use HTTPS.
  - `use_vault` boolean — Opt-in to vault credentials for this run. When true, enabled vault items are included. Defaults to false.
  - `use_profile` boolean — 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_id` string — Browser Context Profile ID to use when use_profile is true.
  - `credential_item_ids` string[] — Scope vault credentials to specific credential URIs. Requires use_vault to be true. If omitted with use_vault: true, all enabled items are used.
  - `proxy_config` object — Proxy configuration
    - `enabled` boolean, required — Enable proxy for this automation run
    - `country_code` 'US' | 'GB' | 'CA' | 'DE' | 'FR' | 'JP' | 'AU' — Country code for proxy location.
  - `output_schema` object — Optional provider-supported structured-output schema subset for the run result. Unsupported fields are rejected before the request is accepted.

## Response `200`

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

- object — Automation run response. Check status to determine success/failure. On success: result is populated, error is null. On failure: result is null, error contains message.
  - `run_id` string, nullable, required — Unique identifier for the automation run
  - `status` 'COMPLETED' | 'FAILED', required — Final status of the automation run
  - `started_at` string, nullable, required — ISO 8601 timestamp when the run started
  - `finished_at` string, nullable, required — ISO 8601 timestamp when the run finished
  - `num_of_steps` number, nullable, required — Number of steps taken during the automation. Null while the run is still in progress.
  - `result` object, nullable, required — Structured JSON result extracted from the automation. Null if the run failed.
  - `error` object, nullable, required — Error details. Null if the run succeeded.
    - `code` string — Machine-readable error code for programmatic handling
    - `message` string, required — Error message describing why the run failed
    - `category` 'SYSTEM_FAILURE' | 'AGENT_FAILURE' | 'BILLING_FAILURE' | 'UNKNOWN', required — Error category. SYSTEM_FAILURE = TinyFish issue (retry). AGENT_FAILURE = run issue (fix input). BILLING_FAILURE = out of credits (add credits). UNKNOWN = unclassified (treat as retryable).
    - `retry_after` number, nullable — Suggested retry delay in seconds (null if not retryable)
    - `help_url` string — URL to documentation for troubleshooting
    - `help_message` string — Human-readable help message with guidance
    - `profile_hint` object — Optional nudge shown when a failed run is likely solvable by setting up a Browser Context Profile.
      - `message` string, required — Human-readable profile setup nudge for auth walls and bot challenges.
      - `setup_url` string, required — Internal URL to set up the caller’s default Browser Context Profile.
      - `reason` 'auth_wall' | 'bot_challenge', required — Why a Browser Context Profile may solve this failed run.
  - `profile_hint` object — Optional nudge shown when a failed run is likely solvable by setting up a Browser Context Profile.
    - `message` string, required — Human-readable profile setup nudge for auth walls and bot challenges.
    - `setup_url` string, required — Internal URL to set up the caller’s default Browser Context Profile.
    - `reason` 'auth_wall' | 'bot_challenge', required — Why a Browser Context Profile may solve this failed run.

## Other responses

- `400` — Invalid request - missing required fields or invalid format
- `401` — Unauthorized - Invalid or missing API key
- `403` — Forbidden - Insufficient credits or no active subscription
- `500` — Server error - Automation failed during execution or internal infrastructure error occurred. Returns run details with error. For infrastructure errors (before run creation), run_id will be null and timestamps will be null.

---

[API](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api.md) · [All operations](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/tinyfish/tinyfish-web-agent-automation-api/revisions/bea716bc627d/schema)