---
title: "Start automation asynchronously"
method: POST
path: "/v1/automation/run-async"
tags: ["Automation"]
---

# Start automation asynchronously

`POST /v1/automation/run-async`

## Request

- Base URL: `https://agent.tinyfish.ai`
- URL: `https://agent.tinyfish.ai/v1/automation/run-async`
- Auth: API key in header `X-API-Key`

Creates and enqueues an automation run, returning the run_id immediately without waiting for completion. Use this for long-running automations where you want to poll for results separately.

## 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`

Run created and enqueued successfully. Returns run_id immediately. The automation will execute asynchronously.

- object: Async automation run response. Returns run_id immediately without waiting for completion.
  - `run_id` string, nullable, required: Unique identifier for the created automation run
  - `error` object, nullable, required: Error details. Null if successful.
    - `code` string, required: Machine-readable error code
    - `message` string, required: Error message if run creation failed

## 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`: Internal server error - Failed to create or enqueue the automation run

---

[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)