> ## Documentation Index > Fetch the complete documentation index at: https://docs.altrina.com/llms.txt > Use this file to discover all available pages before exploring further. # Run a browser agent > Run an AI-powered browser agent. This endpoint launches a browser session where an AI agent will execute your directive. You can watch the agent work in real-time via the history_url or poll our API for results. The agent can navigate websites, interact with page elements like a human, and complete multi-step workflows. Credits are consumed based on the number of steps taken and the VLM model used. ## OpenAPI ````yaml post /v1/run_browser_agent openapi: 3.1.0 info: title: Altrina Browser Agent API description: > AI-powered browser automation API that allows you to control web browsers programmatically. ## What can Altrina do? Altrina uses advanced AI models to understand natural language instructions and execute them in a web browser: - **Web Scraping**: Extract data from any website without writing selectors - **Form Automation**: Fill out complex forms and multi-step workflows - **Testing**: Automated end-to-end testing with natural language assertions - **Research**: Gather information across multiple sites and compile results - **Monitoring**: Check websites for changes or specific conditions ## Authentication All API endpoints (except `/v1/health`) require authentication via API key. ### Getting an API Key 1. Go to [https://app.altrina.com/settings](https://app.altrina.com/settings) 2. Click on "Generate API Key" 3. Copy your API key and keep it secure ### Using the API Key Include your API key in the `Authorization` header as a Bearer token: ``` Authorization: Bearer YOUR_API_KEY ``` ### Example cURL Request ```bash curl -X POST "https://api.altrina.com/v1/run_browser_agent" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "directive": "Go to news.ycombinator.com and get the titles and points of the top 3 stories on the homepage", "browser_config": { "width": 1920, "height": 1080, "residential_ip": false, "keep_browser_open": false, "use_user_browser_profile": false } }' ``` **Note on Browser Profiles**: By default (`use_user_browser_profile: false`), each API call uses a fresh browser profile with no cookies or browsing history. Set `use_user_browser_profile: true` if you need to maintain logged-in state across multiple API calls. ## Rate Limits - **Browser Agent**: 10 requests/minute - **Status Polling**: 60 requests/minute - **Credit Balance**: 60 requests/minute ## Support For issues or questions, contact support@altrina.com version: 1.0.0 servers: - url: https://api.altrina.com security: [] tags: - name: Browser Agent description: Start and monitor browser automation tasks - name: Workflows description: Trigger saved workflows via API or webhook - name: Account description: Manage credits and subscription - name: System description: Service health and status paths: /v1/run_browser_agent: post: tags: - Browser Agent summary: Run a browser agent description: >- Run an AI-powered browser agent. This endpoint launches a browser session where an AI agent will execute your directive. You can watch the agent work in real-time via the history_url or poll our API for results. The agent can navigate websites, interact with page elements like a human, and complete multi-step workflows. Credits are consumed based on the number of steps taken and the VLM model used. operationId: run_browser_agent_endpoint_v1_run_browser_agent_post requestBody: content: application/json: schema: $ref: '#/components/schemas/RunBrowserAgentRequest' required: true responses: '200': description: Browser agent job started successfully content: application/json: schema: $ref: '#/components/schemas/BrowserAgentStartResponse' '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '402': description: Insufficient credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Rate limit exceeded '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - HTTPBearer: [] components: schemas: RunBrowserAgentRequest: properties: directive: type: string title: Directive description: The instruction for the browser agent to execute initial_url: anyOf: - type: string - type: 'null' title: Initial Url description: Starting URL for the browser session cdp_url: anyOf: - type: string - type: 'null' title: Cdp Url description: >- 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: anyOf: - type: string - type: 'null' title: Live Url description: >- Live view URL for your browser session (only used when providing your own cdp_url) action_selection_model: anyOf: - type: string - type: 'null' title: Action Selection Model description: >- 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) default: claude-sonnet-4-20250514 browser_config: anyOf: - $ref: '#/components/schemas/BrowserConfig' - type: 'null' description: >- 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. type: object required: - directive title: RunBrowserAgentRequest BrowserAgentStartResponse: properties: job_id: type: string title: Job Id description: Unique identifier for this job status: $ref: '#/components/schemas/JobRunStatus' description: Initial status of the job (running) live_url: anyOf: - type: string - type: 'null' title: Live Url description: >- Direct link to watch the live browser session. You can observe the agent working in real-time cdp_url: anyOf: - type: string - type: 'null' title: Cdp Url description: Chrome DevTools Protocol URL history_url: type: string title: History Url description: >- Link to the Altrina platform where you can view live session, action history, detailed logs, and take over control polling_url: type: string title: Polling Url description: API endpoint to poll for job status updates type: object required: - job_id - status - history_url - polling_url title: BrowserAgentStartResponse description: Response payload when starting a browser agent job. ErrorResponse: properties: detail: type: string title: Detail description: Detailed error message status_code: type: integer title: Status Code description: HTTP status code type: object required: - detail - status_code title: ErrorResponse description: Standard error response format HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError BrowserConfig: properties: width: type: integer maximum: 4096 minimum: 320 title: Width description: Browser viewport width default: 1920 height: type: integer maximum: 4096 minimum: 320 title: Height description: Browser viewport height default: 1080 residential_ip: anyOf: - type: boolean - type: string title: Residential Ip description: >- Residential proxy setting. False to disable, True for US proxy, or an ISO country code (us, ca, gb, de, fr, au, jp, in, br, kr) default: false max_duration_minutes: type: integer maximum: 240 minimum: 1 title: Max Duration Minutes description: Max session duration in minutes default: 30 idle_timeout_minutes: type: integer maximum: 60 minimum: 1 title: Idle Timeout Minutes description: Idle timeout in minutes default: 2 keep_browser_open: type: boolean title: Keep Browser Open description: Keep browser session open after task completion default: false use_user_browser_profile: type: boolean title: Use User Browser Profile description: >- Use user's persistent browser profile (cookies, localStorage, etc.) instead of a fresh profile for each job. Default is False - each job starts with a clean profile default: false type: object title: BrowserConfig description: Browser configuration options JobRunStatus: type: string enum: - provisioning - running - completed - failed - user_taken_over - paused title: JobRunStatus description: Possible states of a browser agent job ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: HTTPBearer: type: http description: >- API key for authentication. Get your API key at https://app.altrina.com/settings scheme: bearer ````