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

# Start multiple automations asynchronously

`POST /v1/automation/run-batch`

Creates and enqueues multiple automation runs in a single request, returning run_ids immediately without waiting for completion. Maximum 100 runs per request.

**Atomic creation:** Run creation is all-or-nothing. Either all runs are created successfully, or none are (returns error).

**Idempotency:** This endpoint does not currently support idempotency keys. Retrying a failed request may create duplicate runs.

## Request body

- object
  - `runs` object[], required — Array of run configurations (1-100)
    - `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.
    - `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.
  - `profile_id` string — Browser Context Profile ID to use when use_profile is true.
  - `output_schema` object — Optional provider-supported structured-output schema subset applied to every run in the batch. Unsupported fields are rejected before the request is accepted.

## Response `200`

All runs created and enqueued successfully.

- object — Batch async run response. Run creation is atomic. Returns run_ids on success, error on failure.
  - `run_ids` string[], nullable, required — Created run IDs. Null if creation failed.
  - `error` object, nullable, required — Error details. Null if successful.
    - `code` string, required — Error code
    - `message` string, required — Error message

## Other responses

- `400` — Invalid request - missing required fields, invalid format, or exceeds 100 runs
- `401` — Unauthorized - Invalid or missing API key
- `403` — Forbidden - Insufficient credits for the requested number of runs
- `500` — Internal server error - Failed to create or enqueue any runs

---

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