Start automation asynchronously

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.

POST /v1/automation/run-async

Start automation asynchronously

cURL

curl --request POST \
  --url https://agent.tinyfish.ai/v1/automation/run-async \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "url": "https://example.com",
  "goal": "Find the pricing page and extract all plan details",
  "browser_profile": "lite",
  "api_integration": "dify",
  "capture_config": {
    "elements": true,
    "snapshots": true,
    "screenshots": true,
    "recording": true
  },
  "webhook_url": "<string>",
  "use_vault": true,
  "credential_item_ids": [
    "cred:conn-abc:Work:item-123",
    "cred:conn-def:Personal:item-456"
  ]
}
'

200

{
  "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "error": null
}

Authorizations

X-API-Key · string · header · required

API key for authentication. Get your key from the API Keys page.

Body

application/json

Automation task configuration

url · string<uri> · required

Target website URL to automate

Example:

"https://example.com"

goal · string · required

Natural language description of what to accomplish on the website

Minimum string length: 1

Example:

"Find the pricing page and extract all plan details"

browser_profile · enum<string>

Browser profile for execution. LITE uses standard browser, STEALTH uses anti-detection browser.

Available options: lite, stealth

Example:

"lite"

proxy_config · object

Proxy configuration

Show child attributes

api_integration · string

Name of the integration making this API call (e.g., "dify", "zapier", "n8n"). Used for analytics.

Example:

"dify"

capture_config · object

Configure which data to capture during the run.

Show child attributes

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.

Example:

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.

Minimum array length: 1

Minimum string length: 1

Example:

[
  "cred:conn-abc:Work:item-123",
  "cred:conn-def:Personal:item-456"
]

Response

200

application/json

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

Async automation run response. Returns run_id immediately without waiting for completion.

run_id · string | null · required

Unique identifier for the created automation run

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

error · object · required

Error details. Null if successful.

Show child attributes