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",
"api_integration": "dify",
"agent_config": {
"mode": "strict",
"cursor_style": "standard",
"max_steps": 50,
"max_duration_seconds": 300
},
"capture_config": {
"elements": true,
"snapshots": true,
"screenshots": true,
"recording": true,
"html": true
},
"webhook_url": "<string>",
"use_vault": true,
"use_profile": true,
"profile_id": "prof_abc123def4567890",
"credential_item_ids": [
"cred:conn-abc:Work:item-123",
"cred:conn-def:Personal:item-456"
],
"output_schema": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"price": {
"type": "number"
}
},
"required": [
"title",
"price"
]
}
}
'import requests
url = "https://agent.tinyfish.ai/v1/automation/run"
payload = {
"url": "https://example.com",
"goal": "Find the pricing page and extract all plan details",
"browser_profile": "lite",
"api_integration": "dify",
"agent_config": {
"mode": "strict",
"cursor_style": "standard",
"max_steps": 50,
"max_duration_seconds": 300
},
"capture_config": {
"elements": True,
"snapshots": True,
"screenshots": True,
"recording": True,
"html": True
},
"webhook_url": "<string>",
"use_vault": True,
"use_profile": True,
"profile_id": "prof_abc123def4567890",
"credential_item_ids": ["cred:conn-abc:Work:item-123", "cred:conn-def:Personal:item-456"],
"output_schema": {
"type": "object",
"properties": {
"title": { "type": "string" },
"price": { "type": "number" }
},
"required": ["title", "price"]
}
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
url: 'https://example.com',
goal: 'Find the pricing page and extract all plan details',
browser_profile: 'lite',
api_integration: 'dify',
agent_config: {
mode: 'strict',
cursor_style: 'standard',
max_steps: 50,
max_duration_seconds: 300
},
capture_config: {
elements: true,
snapshots: true,
screenshots: true,
recording: true,
html: true
},
webhook_url: '<string>',
use_vault: true,
use_profile: true,
profile_id: 'prof_abc123def4567890',
credential_item_ids: ['cred:conn-abc:Work:item-123', 'cred:conn-def:Personal:item-456'],
output_schema: {
type: 'object',
properties: {title: {type: 'string'}, price: {type: 'number'}},
required: ['title', 'price']
}
})
};
fetch('https://agent.tinyfish.ai/v1/automation/run', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://agent.tinyfish.ai/v1/automation/run",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://example.com',
'goal' => 'Find the pricing page and extract all plan details',
'browser_profile' => 'lite',
'api_integration' => 'dify',
'agent_config' => [
'mode' => 'strict',
'cursor_style' => 'standard',
'max_steps' => 50,
'max_duration_seconds' => 300
],
'capture_config' => [
'elements' => true,
'snapshots' => true,
'screenshots' => true,
'recording' => true,
'html' => true
],
'webhook_url' => '<string>',
'use_vault' => true,
'use_profile' => true,
'profile_id' => 'prof_abc123def4567890',
'credential_item_ids' => [
'cred:conn-abc:Work:item-123',
'cred:conn-def:Personal:item-456'
],
'output_schema' => [
'type' => 'object',
'properties' => [
'title' => [
'type' => 'string'
],
'price' => [
'type' => 'number'
]
],
'required' => [
'title',
'price'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://agent.tinyfish.ai/v1/automation/run"
payload := strings.NewReader("{\n \"url\": \"https://example.com\",\n \"goal\": \"Find the pricing page and extract all plan details\",\n \"browser_profile\": \"lite\",\n \"api_integration\": \"dify\",\n \"agent_config\": {\n \"mode\": \"strict\",\n \"cursor_style\": \"standard\",\n \"max_steps\": 50,\n \"max_duration_seconds\": 300\n },\n \"capture_config\": {\n \"elements\": true,\n \"snapshots\": true,\n \"screenshots\": true,\n \"recording\": true,\n \"html\": true\n },\n \"webhook_url\": \"<string>\",\n \"use_vault\": true,\n \"use_profile\": true,\n \"profile_id\": \"prof_abc123def4567890\",\n \"credential_item_ids\": [\n \"cred:conn-abc:Work:item-123\",\n \"cred:conn-def:Personal:item-456\"\n ],\n \"output_schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"title\": {\n \"type\": \"string\"\n },\n \"price\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"title\",\n \"price\"\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://agent.tinyfish.ai/v1/automation/run")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"https://example.com\",\n \"goal\": \"Find the pricing page and extract all plan details\",\n \"browser_profile\": \"lite\",\n \"api_integration\": \"dify\",\n \"agent_config\": {\n \"mode\": \"strict\",\n \"cursor_style\": \"standard\",\n \"max_steps\": 50,\n \"max_duration_seconds\": 300\n },\n \"capture_config\": {\n \"elements\": true,\n \"snapshots\": true,\n \"screenshots\": true,\n \"recording\": true,\n \"html\": true\n },\n \"webhook_url\": \"<string>\",\n \"use_vault\": true,\n \"use_profile\": true,\n \"profile_id\": \"prof_abc123def4567890\",\n \"credential_item_ids\": [\n \"cred:conn-abc:Work:item-123\",\n \"cred:conn-def:Personal:item-456\"\n ],\n \"output_schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"title\": {\n \"type\": \"string\"\n },\n \"price\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"title\",\n \"price\"\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agent.tinyfish.ai/v1/automation/run")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"https://example.com\",\n \"goal\": \"Find the pricing page and extract all plan details\",\n \"browser_profile\": \"lite\",\n \"api_integration\": \"dify\",\n \"agent_config\": {\n \"mode\": \"strict\",\n \"cursor_style\": \"standard\",\n \"max_steps\": 50,\n \"max_duration_seconds\": 300\n },\n \"capture_config\": {\n \"elements\": true,\n \"snapshots\": true,\n \"screenshots\": true,\n \"recording\": true,\n \"html\": true\n },\n \"webhook_url\": \"<string>\",\n \"use_vault\": true,\n \"use_profile\": true,\n \"profile_id\": \"prof_abc123def4567890\",\n \"credential_item_ids\": [\n \"cred:conn-abc:Work:item-123\",\n \"cred:conn-def:Personal:item-456\"\n ],\n \"output_schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"title\": {\n \"type\": \"string\"\n },\n \"price\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"title\",\n \"price\"\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"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
}Automation
Run browser automation synchronously
Execute a browser automation task synchronously and wait for completion. Returns the final result once the automation finishes (success or failure). Use this endpoint when you need the complete result in a single response. Note: Runs created via this endpoint cannot be cancelled. If you need cancellation support, use /v1/automation/run-async or /v1/automation/run-sse instead.
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",
"api_integration": "dify",
"agent_config": {
"mode": "strict",
"cursor_style": "standard",
"max_steps": 50,
"max_duration_seconds": 300
},
"capture_config": {
"elements": true,
"snapshots": true,
"screenshots": true,
"recording": true,
"html": true
},
"webhook_url": "<string>",
"use_vault": true,
"use_profile": true,
"profile_id": "prof_abc123def4567890",
"credential_item_ids": [
"cred:conn-abc:Work:item-123",
"cred:conn-def:Personal:item-456"
],
"output_schema": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"price": {
"type": "number"
}
},
"required": [
"title",
"price"
]
}
}
'import requests
url = "https://agent.tinyfish.ai/v1/automation/run"
payload = {
"url": "https://example.com",
"goal": "Find the pricing page and extract all plan details",
"browser_profile": "lite",
"api_integration": "dify",
"agent_config": {
"mode": "strict",
"cursor_style": "standard",
"max_steps": 50,
"max_duration_seconds": 300
},
"capture_config": {
"elements": True,
"snapshots": True,
"screenshots": True,
"recording": True,
"html": True
},
"webhook_url": "<string>",
"use_vault": True,
"use_profile": True,
"profile_id": "prof_abc123def4567890",
"credential_item_ids": ["cred:conn-abc:Work:item-123", "cred:conn-def:Personal:item-456"],
"output_schema": {
"type": "object",
"properties": {
"title": { "type": "string" },
"price": { "type": "number" }
},
"required": ["title", "price"]
}
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
url: 'https://example.com',
goal: 'Find the pricing page and extract all plan details',
browser_profile: 'lite',
api_integration: 'dify',
agent_config: {
mode: 'strict',
cursor_style: 'standard',
max_steps: 50,
max_duration_seconds: 300
},
capture_config: {
elements: true,
snapshots: true,
screenshots: true,
recording: true,
html: true
},
webhook_url: '<string>',
use_vault: true,
use_profile: true,
profile_id: 'prof_abc123def4567890',
credential_item_ids: ['cred:conn-abc:Work:item-123', 'cred:conn-def:Personal:item-456'],
output_schema: {
type: 'object',
properties: {title: {type: 'string'}, price: {type: 'number'}},
required: ['title', 'price']
}
})
};
fetch('https://agent.tinyfish.ai/v1/automation/run', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://agent.tinyfish.ai/v1/automation/run",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://example.com',
'goal' => 'Find the pricing page and extract all plan details',
'browser_profile' => 'lite',
'api_integration' => 'dify',
'agent_config' => [
'mode' => 'strict',
'cursor_style' => 'standard',
'max_steps' => 50,
'max_duration_seconds' => 300
],
'capture_config' => [
'elements' => true,
'snapshots' => true,
'screenshots' => true,
'recording' => true,
'html' => true
],
'webhook_url' => '<string>',
'use_vault' => true,
'use_profile' => true,
'profile_id' => 'prof_abc123def4567890',
'credential_item_ids' => [
'cred:conn-abc:Work:item-123',
'cred:conn-def:Personal:item-456'
],
'output_schema' => [
'type' => 'object',
'properties' => [
'title' => [
'type' => 'string'
],
'price' => [
'type' => 'number'
]
],
'required' => [
'title',
'price'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://agent.tinyfish.ai/v1/automation/run"
payload := strings.NewReader("{\n \"url\": \"https://example.com\",\n \"goal\": \"Find the pricing page and extract all plan details\",\n \"browser_profile\": \"lite\",\n \"api_integration\": \"dify\",\n \"agent_config\": {\n \"mode\": \"strict\",\n \"cursor_style\": \"standard\",\n \"max_steps\": 50,\n \"max_duration_seconds\": 300\n },\n \"capture_config\": {\n \"elements\": true,\n \"snapshots\": true,\n \"screenshots\": true,\n \"recording\": true,\n \"html\": true\n },\n \"webhook_url\": \"<string>\",\n \"use_vault\": true,\n \"use_profile\": true,\n \"profile_id\": \"prof_abc123def4567890\",\n \"credential_item_ids\": [\n \"cred:conn-abc:Work:item-123\",\n \"cred:conn-def:Personal:item-456\"\n ],\n \"output_schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"title\": {\n \"type\": \"string\"\n },\n \"price\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"title\",\n \"price\"\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://agent.tinyfish.ai/v1/automation/run")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"https://example.com\",\n \"goal\": \"Find the pricing page and extract all plan details\",\n \"browser_profile\": \"lite\",\n \"api_integration\": \"dify\",\n \"agent_config\": {\n \"mode\": \"strict\",\n \"cursor_style\": \"standard\",\n \"max_steps\": 50,\n \"max_duration_seconds\": 300\n },\n \"capture_config\": {\n \"elements\": true,\n \"snapshots\": true,\n \"screenshots\": true,\n \"recording\": true,\n \"html\": true\n },\n \"webhook_url\": \"<string>\",\n \"use_vault\": true,\n \"use_profile\": true,\n \"profile_id\": \"prof_abc123def4567890\",\n \"credential_item_ids\": [\n \"cred:conn-abc:Work:item-123\",\n \"cred:conn-def:Personal:item-456\"\n ],\n \"output_schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"title\": {\n \"type\": \"string\"\n },\n \"price\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"title\",\n \"price\"\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agent.tinyfish.ai/v1/automation/run")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"https://example.com\",\n \"goal\": \"Find the pricing page and extract all plan details\",\n \"browser_profile\": \"lite\",\n \"api_integration\": \"dify\",\n \"agent_config\": {\n \"mode\": \"strict\",\n \"cursor_style\": \"standard\",\n \"max_steps\": 50,\n \"max_duration_seconds\": 300\n },\n \"capture_config\": {\n \"elements\": true,\n \"snapshots\": true,\n \"screenshots\": true,\n \"recording\": true,\n \"html\": true\n },\n \"webhook_url\": \"<string>\",\n \"use_vault\": true,\n \"use_profile\": true,\n \"profile_id\": \"prof_abc123def4567890\",\n \"credential_item_ids\": [\n \"cred:conn-abc:Work:item-123\",\n \"cred:conn-def:Personal:item-456\"\n ],\n \"output_schema\": {\n \"type\": \"object\",\n \"properties\": {\n \"title\": {\n \"type\": \"string\"\n },\n \"price\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"title\",\n \"price\"\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"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
API key for authentication. Get your key from the API Keys page.
Body
application/json
Automation task parameters
Target website URL to automate
Example:
"https://example.com"
Natural language description of what to accomplish on the website
Minimum string length:
1Example:
"Find the pricing page and extract all plan details"
Browser profile for execution. LITE uses standard browser, STEALTH uses anti-detection browser.
Available options:
lite, stealth Example:
"lite"
Name of the integration making this API call (e.g., "dify", "zapier", "n8n"). Used for analytics.
Example:
"dify"
Agent behavior configuration
Show child attributes
Show child attributes
Configure which data to capture during the run.
Show child attributes
Show child attributes
HTTPS URL to receive webhook notifications for run lifecycle events. Must use HTTPS.
Opt-in to vault credentials for this run. When true, enabled vault items are included. Defaults to false.
Example:
true
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.
Example:
true
Browser Context Profile ID to use when use_profile is true.
Minimum string length:
1Example:
"prof_abc123def4567890"
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:
1Minimum string length:
1Example:
[
"cred:conn-abc:Work:item-123",
"cred:conn-def:Personal:item-456"
]
Proxy configuration
Show child attributes
Show child attributes
Optional provider-supported structured-output schema subset for the run result. Unsupported fields are rejected before the request is accepted.
Show child attributes
Show child attributes
Example:
{
"type": "object",
"properties": {
"title": { "type": "string" },
"price": { "type": "number" }
},
"required": ["title", "price"]
}
Response
Automation completed or failed after execution started. Returns run details.
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.
Unique identifier for the automation run
Example:
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
Final status of the automation run
Available options:
COMPLETED, FAILED Example:
"COMPLETED"
ISO 8601 timestamp when the run started
Example:
"2024-01-01T00:00:00Z"
ISO 8601 timestamp when the run finished
Example:
"2024-01-01T00:00:30Z"
Number of steps taken during the automation. Null while the run is still in progress.
Example:
5
Structured JSON result extracted from the automation. Null if the run failed.
Show child attributes
Show child attributes
Example:
{ "product": "iPhone 15", "price": "$799" }
Error details. Null if the run succeeded.
Show child attributes
Show child attributes
Optional nudge shown when a failed run is likely solvable by setting up a Browser Context Profile.
Show child attributes
Show child attributes
Was this page helpful?