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

# Start multiple automations asynchronously

`POST /v1/automation/run-batch`

## Request

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

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` string: Proxy exit country (ISO 3166-1 alpha-2). Defaults to US.
  - `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
    - `details` unknown

## Other responses

- `400`: Invalid request - missing required fields, invalid format, or exceeds 100 runs
- `401`: Unauthorized - Invalid or missing API key
- `402`: Payment required - wallet balance too low for the requested number of runs
- `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-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)