> ## Documentation Index > Fetch the complete documentation index at: https://docs.tinyfish.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml https://agent.tinyfish.ai/v1/openapi/main post /v1/automation/run openapi: 3.0.0 info: title: TinyFish Web Agent Automation API version: 1.0.0 description: >- REST API for running AI-powered browser automations. Execute tasks on any website using natural language instructions. contact: name: TinyFish Support email: support@tinyfish.ai servers: - url: https://agent.tinyfish.ai description: Production security: [] tags: - name: Automation description: Browser automation endpoints for executing tasks on websites - name: Runs description: Endpoints for retrieving automation run data - name: Browser description: Remote browser session endpoints - name: Fetch description: Fetch URLs and extract clean page content - name: Search description: Web search endpoints - name: Browser Context Profiles description: >- Saved browser context endpoints for managing reusable login state, cookies, storage, and profile setup sessions - name: Vault description: >- Vault credential management endpoints for connecting password managers and managing stored credentials paths: /v1/automation/run: post: tags: - Automation summary: Run browser automation synchronously description: >- 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. operationId: run requestBody: description: Automation task parameters content: application/json: schema: type: object properties: url: type: string format: uri description: Target website URL to automate example: https://example.com goal: type: string minLength: 1 description: >- Natural language description of what to accomplish on the website example: Find the pricing page and extract all plan details browser_profile: type: string enum: - lite - stealth description: >- Browser profile for execution. LITE uses standard browser, STEALTH uses anti-detection browser. example: lite api_integration: type: string description: >- Name of the integration making this API call (e.g., "dify", "zapier", "n8n"). Used for analytics. example: dify agent_config: type: object properties: mode: type: string enum: - default - strict description: >- Agent behavior mode. "strict" enables fail-fast for test automation. example: strict cursor_style: type: string enum: - fish - standard - green-pointer description: Cursor style for the browser agent. example: standard max_steps: type: integer minimum: 1 maximum: 500 description: >- Maximum tool-call steps before the agent stops. Defaults to 150. example: 50 max_duration_seconds: type: integer minimum: 1 description: >- Maximum wall-clock seconds before the agent stops. Defaults to no limit. example: 300 description: Agent behavior configuration capture_config: type: object properties: elements: type: boolean snapshots: type: boolean screenshots: type: boolean recording: type: boolean html: type: boolean description: Configure which data to capture during the run. webhook_url: type: string format: uri description: >- HTTPS URL to receive webhook notifications for run lifecycle events. Must use HTTPS. use_vault: type: boolean description: >- Opt-in to vault credentials for this run. When true, enabled vault items are included. Defaults to false. example: true use_profile: type: boolean description: >- 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. example: true profile_id: type: string minLength: 1 description: Browser Context Profile ID to use when use_profile is true. example: prof_abc123def4567890 credential_item_ids: type: array items: type: string minLength: 1 minItems: 1 description: >- Scope vault credentials to specific credential URIs. Requires use_vault to be true. If omitted with use_vault: true, all enabled items are used. example: - cred:conn-abc:Work:item-123 - cred:conn-def:Personal:item-456 proxy_config: type: object properties: enabled: type: boolean description: Enable proxy for this automation run example: true country_code: type: string enum: - US - GB - CA - DE - FR - JP - AU description: Country code for proxy location. example: US required: - enabled description: Proxy configuration output_schema: type: object properties: {} additionalProperties: nullable: true description: >- Optional provider-supported structured-output schema subset for the run result. Unsupported fields are rejected before the request is accepted. example: type: object properties: title: type: string price: type: number required: - title - price required: - url - goal responses: '200': description: >- Automation completed successfully. Returns run details and the extracted result. content: application/json: schema: type: object properties: run_id: type: string nullable: true description: Unique identifier for the automation run example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 status: type: string enum: - COMPLETED - FAILED description: Final status of the automation run example: COMPLETED started_at: type: string nullable: true description: ISO 8601 timestamp when the run started example: '2024-01-01T00:00:00Z' finished_at: type: string nullable: true description: ISO 8601 timestamp when the run finished example: '2024-01-01T00:00:30Z' num_of_steps: type: number nullable: true description: >- Number of steps taken during the automation. Null while the run is still in progress. example: 5 result: type: object nullable: true additionalProperties: nullable: true description: >- Structured JSON result extracted from the automation. Null if the run failed. example: product: iPhone 15 price: $799 error: type: object nullable: true properties: code: type: string description: Machine-readable error code for programmatic handling example: service_busy message: type: string description: Error message describing why the run failed example: Browser crashed during execution category: type: string enum: - SYSTEM_FAILURE - AGENT_FAILURE - BILLING_FAILURE - UNKNOWN description: >- 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). example: SYSTEM_FAILURE retry_after: type: number nullable: true description: >- Suggested retry delay in seconds (null if not retryable) example: 60 help_url: type: string description: URL to documentation for troubleshooting example: https://docs.tinyfish.ai/prompting-guide help_message: type: string description: Human-readable help message with guidance example: >- Need help? Check out our goal prompting guide for tips and examples. profile_hint: type: object properties: message: type: string description: >- Human-readable profile setup nudge for auth walls and bot challenges. setup_url: type: string description: >- Internal URL to set up the caller’s default Browser Context Profile. example: >- /profiles/prof_abc123/setup?domain=example.com&returnTo=%2Fruns%2Frun_123&ref=run_error_nudge reason: type: string enum: - auth_wall - bot_challenge description: >- Why a Browser Context Profile may solve this failed run. example: auth_wall required: - message - setup_url - reason description: >- Optional nudge shown when a failed run is likely solvable by setting up a Browser Context Profile. required: - message - category description: Error details. Null if the run succeeded. profile_hint: type: object properties: message: type: string description: >- Human-readable profile setup nudge for auth walls and bot challenges. setup_url: type: string description: >- Internal URL to set up the caller’s default Browser Context Profile. example: >- /profiles/prof_abc123/setup?domain=example.com&returnTo=%2Fruns%2Frun_123&ref=run_error_nudge reason: type: string enum: - auth_wall - bot_challenge description: >- Why a Browser Context Profile may solve this failed run. example: auth_wall required: - message - setup_url - reason description: >- Optional nudge shown when a failed run is likely solvable by setting up a Browser Context Profile. required: - run_id - status - started_at - finished_at - num_of_steps - result - error description: >- 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. example: 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: null '400': description: Invalid request - missing required fields or invalid format content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message request_id: type: string description: >- Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues. example: 8f9dba20-e37b-4749-a919-2269e28b4a2c required: - error description: Standard error response format '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message request_id: type: string description: >- Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues. example: 8f9dba20-e37b-4749-a919-2269e28b4a2c required: - error description: Standard error response format '403': description: Forbidden - Insufficient credits or no active subscription content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message request_id: type: string description: >- Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues. example: 8f9dba20-e37b-4749-a919-2269e28b4a2c required: - error description: Standard error response format '500': description: >- 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. content: application/json: schema: type: object properties: run_id: type: string nullable: true description: Unique identifier for the automation run example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 status: type: string enum: - COMPLETED - FAILED description: Final status of the automation run example: COMPLETED started_at: type: string nullable: true description: ISO 8601 timestamp when the run started example: '2024-01-01T00:00:00Z' finished_at: type: string nullable: true description: ISO 8601 timestamp when the run finished example: '2024-01-01T00:00:30Z' num_of_steps: type: number nullable: true description: >- Number of steps taken during the automation. Null while the run is still in progress. example: 5 result: type: object nullable: true additionalProperties: nullable: true description: >- Structured JSON result extracted from the automation. Null if the run failed. example: product: iPhone 15 price: $799 error: type: object nullable: true properties: code: type: string description: Machine-readable error code for programmatic handling example: service_busy message: type: string description: Error message describing why the run failed example: Browser crashed during execution category: type: string enum: - SYSTEM_FAILURE - AGENT_FAILURE - BILLING_FAILURE - UNKNOWN description: >- 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). example: SYSTEM_FAILURE retry_after: type: number nullable: true description: >- Suggested retry delay in seconds (null if not retryable) example: 60 help_url: type: string description: URL to documentation for troubleshooting example: https://docs.tinyfish.ai/prompting-guide help_message: type: string description: Human-readable help message with guidance example: >- Need help? Check out our goal prompting guide for tips and examples. profile_hint: type: object properties: message: type: string description: >- Human-readable profile setup nudge for auth walls and bot challenges. setup_url: type: string description: >- Internal URL to set up the caller’s default Browser Context Profile. example: >- /profiles/prof_abc123/setup?domain=example.com&returnTo=%2Fruns%2Frun_123&ref=run_error_nudge reason: type: string enum: - auth_wall - bot_challenge description: >- Why a Browser Context Profile may solve this failed run. example: auth_wall required: - message - setup_url - reason description: >- Optional nudge shown when a failed run is likely solvable by setting up a Browser Context Profile. required: - message - category description: Error details. Null if the run succeeded. profile_hint: type: object properties: message: type: string description: >- Human-readable profile setup nudge for auth walls and bot challenges. setup_url: type: string description: >- Internal URL to set up the caller’s default Browser Context Profile. example: >- /profiles/prof_abc123/setup?domain=example.com&returnTo=%2Fruns%2Frun_123&ref=run_error_nudge reason: type: string enum: - auth_wall - bot_challenge description: >- Why a Browser Context Profile may solve this failed run. example: auth_wall required: - message - setup_url - reason description: >- Optional nudge shown when a failed run is likely solvable by setting up a Browser Context Profile. required: - run_id - status - started_at - finished_at - num_of_steps - result - error description: >- 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. examples: automationFailed: summary: Automation execution failed value: run_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 status: FAILED started_at: '2024-01-01T00:00:00Z' finished_at: '2024-01-01T00:00:15Z' num_of_steps: 3 result: null error: message: Browser crashed during execution infrastructureError: summary: Infrastructure error (before run creation) value: run_id: null status: FAILED started_at: null finished_at: null num_of_steps: 0 result: null error: message: Internal server error security: - ApiKeyAuth: [] components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key for authentication. Get your key from the API Keys page. ````