Skip to main content
POST
/
v1
/
run_browser_agent
Run a browser agent
curl --request POST \
  --url https://api.example.com/v1/run_browser_agent \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "directive": "<string>",
  "initial_url": "<string>",
  "cdp_url": "<string>",
  "live_url": "<string>",
  "action_selection_model": "claude-sonnet-4-20250514",
  "shadow_dom_beta": false,
  "browser_config": {
    "width": 1920,
    "height": 1080,
    "residential_ip": false,
    "max_duration_minutes": 30,
    "idle_timeout_minutes": 2,
    "keep_browser_open": false,
    "use_user_browser_profile": false
  }
}
'
{
  "job_id": "<string>",
  "status": "running",
  "history_url": "<string>",
  "polling_url": "<string>",
  "live_url": "<string>",
  "cdp_url": "<string>"
}

Authorizations

​
Authorization
string
header
required

API key for authentication. Get your API key at https://app.altrina.com/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 Altrina 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
BrowserConfig · object

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 Altrina 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,
paused
​
history_url
string
required

Link to the Altrina 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