Skip to main content
POST
/
v1
/
automation
/
run
Run browser automation synchronously
curl --request POST \
  --url https://agent.tinyfish.ai/v1/automation/run \
  --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",
  "proxy_config": {
    "enabled": true,
    "country_code": "US"
  },
  "api_integration": "dify",
  "feature_flags": {
    "enable_agent_memory": true
  },
  "use_vault": true,
  "credential_item_ids": [
    "item_abc123",
    "item_def456"
  ]
}
'
{ "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "COMPLETED", "started_at": "2024-01-01T00:00:00Z", "finished_at": "2024-01-01T00:00:30Z", "num_of_steps": 5, "result": { "product": "iPhone 15", "price": "$799" }, "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 parameters

​
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

​
api_integration
string

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

Example:

"dify"

​
feature_flags
object

Feature flags to enable for this run

​
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 item IDs. 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:
["item_abc123", "item_def456"]

Response

Automation completed successfully. Returns run details and the extracted result.

Automation run response. Check status to determine success/failure. On success: result is populated, error is null. On failure: result is null, error contains message.

​
run_id
string | null
required

Unique identifier for the automation run

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

​
status
enum<string>
required

Final status of the automation run

Available options:
COMPLETED,
FAILED
Example:

"COMPLETED"

​
started_at
string | null
required

ISO 8601 timestamp when the run started

Example:

"2024-01-01T00:00:00Z"

​
finished_at
string | null
required

ISO 8601 timestamp when the run finished

Example:

"2024-01-01T00:00:30Z"

​
num_of_steps
number
required

Number of steps taken during the automation

Example:

5

​
result
object
required

Structured JSON result extracted from the automation. Null if the run failed.

Example:
{ "product": "iPhone 15", "price": "$799" }
​
error
object
required

Error details. Null if the run succeeded.