Skip to main content
POST
/
v1
/
run_browser_agent
{
  "job_id": "<string>",
  "status": "running",
  "live_url": "<string>",
  "cdp_url": "<string>",
  "history_url": "<string>",
  "polling_url": "<string>"
}

Authorizations

​
Authorization
string
header
required

API key for authentication. Get your API key at https://app.heytessa.ai/settings

Body

application/json
​
directive
string
required

The instruction for the browser agent to execute

​
initial_url
string | null

Starting URL for the browser session

​
cdp_url
string | null

Chrome DevTools Protocol URL if you want to run Tessa on your own browser. When provided, the API will connect to your existing browser instead of provisioning a new one

​
live_url
string | null

Live view URL for your browser session (only used when providing your own cdp_url)

​
action_selection_model
string | null
default:claude-sonnet-4-20250514

VLM model to use for action selection. Options: claude-sonnet-4-20250514 (5 credits/step), gemini/gemini-2.5-flash (1 credit/step), o3 (3 credits/step), claude-opus-4-1-20250805 (25 credits/step), gpt-4o (5 credits/step)

​
shadow_dom_beta
boolean
default:false

Enable advanced shadow DOM functionality with closed shadow root support. Feature is in beta. Exercise caution in critical applications.

​
browser_config
object | null

Browser configuration options. NOTE: These options are only applied when the API provisions the browser (no user-provided CDP URL). If you are connecting to your own browser, provide cdp_url (required) and optionally live_url if you want to view it in the Tessa platform.

Response

Browser agent job started successfully

Response payload when starting a browser agent job.

​
job_id
string
required

Unique identifier for this job

​
status
enum<string>
required

Initial status of the job (running)

Available options:
running,
completed,
failed,
user_taken_over
​
history_url
string
required

Link to the Tessa platform where you can view live session, action history, detailed logs, and take over control

​
polling_url
string
required

API endpoint to poll for job status updates

​
live_url
string | null

Direct link to watch the live browser session. You can observe the agent working in real-time

​
cdp_url
string | null

Chrome DevTools Protocol URL

⌘I