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

# Start automation asynchronously

`POST /v1/automation/run-async`

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

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
- `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.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)