--- title: "Run browser automation synchronously" method: POST path: "/v1/automation/run" tags: ["Automation"] --- # Run browser automation synchronously `POST /v1/automation/run` ## Request - Base URL: `https://agent.tinyfish.ai` - URL: `https://agent.tinyfish.ai/v1/automation/run` - Auth: API key in header `X-API-Key` 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` string: Proxy exit country (ISO 3166-1 alpha-2). Defaults to US. - `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 or failed after execution started. Returns run details. - 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 - `402`: Payment required - wallet balance too low to start this run - `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-2.md) · [All operations](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2/revisions/6c73a54df35c?raw)