Skip to main content
POST
Run a browser agent

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-3-flash-preview (1 credit/step), o3 (3 credits/step), claude-opus-4-1-20250805 (25 credits/step), gpt-4o (5 credits/step)

browser_config
BrowserConfig · 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 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:
provisioning,
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