Skip to main content
POST
/
v1
/
automation
/
run-sse
Run browser automation with SSE streaming
curl --request POST \
  --url https://agent.tinyfish.ai/v1/automation/run-sse \
  --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"
    ]
  }
}
'
"data: {\"type\":\"STARTED\",\"run_id\":\"run_123\",\"timestamp\":\"2025-01-01T00:00:00Z\"}\n\ndata: {\"type\":\"STREAMING_URL\",\"run_id\":\"run_123\",\"streaming_url\":\"https://...\",\"timestamp\":\"...\"}\n\ndata: {\"type\":\"PROGRESS\",\"run_id\":\"run_123\",\"purpose\":\"Clicking submit button\",\"timestamp\":\"...\"}\n\ndata: {\"type\":\"COMPLETE\",\"run_id\":\"run_123\",\"status\":\"COMPLETED\",\"result\":{...},\"timestamp\":\"...\"}"

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"

​
api_integration
string

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

Example:

"dify"

​
agent_config
object

Agent behavior configuration

​
capture_config
object

Configure which data to capture during the run.

​
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

​
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.

Example:

true

​
profile_id
string

Browser Context Profile ID to use when use_profile is true.

Minimum string length: 1
Example:

"prof_abc123def4567890"

​
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"
]
​
proxy_config
object

Proxy configuration

​
output_schema
object

Optional provider-supported structured-output schema subset for the run result. Unsupported fields are rejected before the request is accepted.

Example:
{
  "type": "object",
  "properties": {
    "title": { "type": "string" },
    "price": { "type": "number" }
  },
  "required": ["title", "price"]
}

Response

Server-Sent Events stream. Stream sends STARTED, STREAMING_URL (optional), PROGRESS (intermediate events with purpose), COMPLETE events, plus periodic HEARTBEAT messages.

​
type
enum<string>
required
Available options:
STARTED
​
run_id
string
required
​
timestamp
string
required