Session Management

POST /v1/sessions

Create and queue a new browser session. This endpoint features a smart long-polling mechanism (up to 15 seconds), holding the connection open to wait for the session to leave the "queued" state before returning. This minimizes the need for immediate retry loops.

Browser coordinates:

  • Browser window size: (width, height): (1280, 1024)
  • Viewport frame size: (width, height): (1279, 936)

Request Body (JSON):

  • enable_proxy (boolean, optional): Whether to enable built-in residential proxy routing for this session. Default is false.
  • rotate_proxy (boolean, optional): If true, the browser will iterate proxy tiers, policies and locations to find a combination that can access the target site. Note: this option may significantly increase proxy bandwidth usage. Default is false.
  • proxy_tier (string, optional): The quality tier of the residential proxy network.
    • "lite" (Default if enable_proxy is enabled): The most affordable residential network.
    • "basic": Standard residential network, good for most common anti-bot protections.
    • "premium": Higher-quality proxy network with better success rates for strict anti-bot protections.
  • proxy_policy (string, optional): Defines what type of traffic is routed through the proxy to help optimize bandwidth costs.
    • "html_only": Proxies only HTML documents.
    • "basic" (Default if enable_proxy is enabled): Proxies HTML, XHR and WebSockets.
    • "extended": Proxies everything in basic plus JavaScript files and their child requests.
    • "full": Routes all traffic through the proxy including media.
  • country (string, optional): Target ISO country code for the proxy (e.g., "US", "GB").
  • city (string, optional): Target city for the proxy. Supported cities depend on the selected country. If not provided, a random location within the selected country will be chosen.
  • block_unproxied (boolean, optional): If true, any web traffic that is not routed through the proxy (based on your proxy_policy) will be completely blocked instead of bypassing the proxy. Might be useful when you don't want to expose browser IP to website for non-'full' policies. Default is false.
  • cookies (array of objects, optional): An array of cookie objects to inject into the new browser session. Each object must contain name, value and domain.
  • session_timeout (float, optional): Absolute maximum time (in seconds) the session can exist before it self-terminates. Maximum value is 3600.0 (1 hour). Defaults to 3600.0.

Response Example:

json
{
  "success": true,
  "session_id": "8a7b6c5d-4e3f-2g1h-9i8j-7k6l5m4n3o2p",
  "status": "queued",
  "created_at": "2026-05-01T12:00:00Z"
}

If the session successfully transitions to "idle" before the connection closes, it may also include a "browser" object containing the browser and viewport details.

Session Statuses:

  • queued: waiting for an available worker
  • initializing: a worker was assigned and the browser is starting
  • idle: ready to accept the next command
  • busy: currently executing a command
  • terminated: ended normally, for example by timeout or natural completion
  • stopped: explicitly stopped by the user
  • failed: ended due to an unrecoverable error
  • cancelled: queue wait expired before the session was assigned

Notes:

  • A session stays alive until you stop it or it expires.
  • Only one command can run at a time for a session.
  • A session may remain reusable across many execute calls.

GET /v1/sessions

List all your past and active browser sessions, sorted by creation date (newest first).

Note: Video recordings of sessions are retained for 60 days. For sessions older than 60 days, the video_url field will be null.

Query Parameters:

  • limit (integer, optional): Maximum number of sessions to return. Maximum 30, Default 10.
  • offset (integer, optional): Pagination offset. Default 0.
  • status (string, optional): Filter returned sessions by a specific status (e.g., "idle", "failed").

Response Example:

json
{
  "success": true,
  "sessions": [
    {
      "session_id": "8a7b6c5d-4e3f-2g1h-9i8j-7k6l5m4n3o2p",
      "is_active": true,
      "status": "idle",
      "created_at": "2026-05-01T12:00:00Z",
      "current_url": "https://example.com",
      "command_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
      "error_name": null,
      "error_message": null,
      "billing": {
        "last_synced_at": "2026-05-01T12:05:00Z",
        "total_billed": 0.05,
        "breakdown": {
          "runner": 0.01,
          "proxy": 0.02,
          "llm": 0.01,
          "grounding": 0.01,
          "ocr": 0.00
        }
      },
      "proxy_usage": {
        "total_traffic_mb": 1.5,
        "total_flows": 45,
        "total_errors": 0,
        "error_rate": 0.0,
        "avg_latency_ms": 120.5,
        "min_latency_ms": 40.0,
        "max_latency_ms": 250.0,
        "median_latency_ms": 110.0,
        "p95_latency_ms": 200.0
      },
      "tokens": {
        "total": 1500,
        "prompt": 1000,
        "completion": 500
      },
      "stream_url": "https://stream.getbro.ws/8a7b6c5d-4e3f-2g1h-9i8j-7k6l5m4n3o2p",
      "video_url": "https://storage.googleapis.com/videos/video.mp4",
      "browser": {
        "browser_version": "Chrome/148.0.7778.167",
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.7778.167 Safari/537.36",
        "window_width": 1280,
        "window_height": 1024,
        "window_x": 0,
        "window_y": 0,
        "viewport_width": 1279,
        "viewport_height": 936,
        "viewport_x1": 0,
        "viewport_y1": 88,
        "viewport_x2": 1279,
        "viewport_y2": 1024
      }
    }
  ]
}

Response Parameters:

  • success: Boolean indicating if the request was successful.
  • sessions: An array of session objects. Each session object contains:
    • session_id: The unique identifier of the session.
    • is_active: Boolean indicating if the session is currently active and running.
    • status: The current status of the session (e.g., "idle", "busy", "queued", "terminated", "stopped", "failed").
    • created_at: ISO 8601 timestamp of when the session was created.
    • current_url: The URL the browser is currently at.
    • command_id: The ID of the command currently being executed (if "busy").
    • error_name: The name of the error if the session failed.
    • error_message: A descriptive message of the error if the session failed.
    • billing: Object containing detailed billing metrics for the session.
      • last_synced_at: Timestamp of the last billing sync.
      • total_billed: Total cost billed for the session.
      • breakdown: Cost breakdown by resource (runner, proxy, llm, grounding, ocr).
    • proxy_usage: Object containing metrics for the proxy network (e.g., total_traffic_mb, total_flows, error_rate, latencies).
    • tokens: Object tracking LLM token consumption (total, prompt, completion).
    • stream_url: Live stream URL for the browser session.
    • video_url: Session video URL hosted in the cloud.
    • browser: Object containing metadata about the actual browser instance executing the session.
      • browser_version: The underlying browser's version string.
      • user_agent: The user agent string exposed to websites.
      • window_width, window_height: The dimensions of the entire browser window in pixels.
      • window_x, window_y: The screen coordinates of the top-left corner of the browser window.
      • viewport_width, viewport_height: The dimensions of the inner area displaying the webpage.
      • viewport_x1, viewport_y1, viewport_x2, viewport_y2: The OS screen coordinates bounding the viewport area.

GET /v1/sessions/{session_id}

Retrieve the detailed real-time status, billing breakdown and proxy/AI usage of a specific session. This endpoint features long-polling: if the session is "queued" or "initializing", the connection stays open (up to 15 seconds) waiting for it to become "idle" or "failed".

Note: Video recordings of sessions are retained for 60 days. If a session is older than 60 days, the video_url field will be null.

Path Parameters:

  • session_id (string): The unique identifier of the session.

Response Example: The response format is identical to the individual session objects returned in the GET /v1/sessions list.

DELETE /v1/sessions/{session_id}

Gracefully shut down an active browser session. The instance will finish its current initialization or operation and then safely terminate. You will only be billed up to the point of termination.

Path Parameters:

  • session_id (string): The unique identifier of the session.

Response Example:

json
{
  "success": true,
  "session_id": "8a7b6c5d-4e3f-2g1h-9i8j-7k6l5m4n3o2p",
  "status": "stopped"
}

GET /v1/sessions/{session_id}/commands

List all executed commands within a given session, sorted from newest to oldest.

Path Parameters:

  • session_id (string): The unique identifier of the session.

Query Parameters:

  • limit (integer, optional): Maximum number of commands to return. Maximum 100, Default 50.
  • start_after (string, optional): The command_id to start paginating after.
  • status (string, optional): Filter commands by status (e.g., "done", "failed").

Response Example:

json
{
  "success": true,
  "has_more": false,
  "commands": [
    {
      "command_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
      "status": "done",
      "command": "open_url",
      "created_at": "2026-05-01T12:05:00Z",
      "finished_at": "2026-05-01T12:05:15Z"
    },
    {
      "command_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
      "status": "done",
      "command": "extract",
      "created_at": "2026-05-01T12:04:58Z",
      "finished_at": "2026-05-01T12:05:00Z"
    }
  ]
}

GET /v1/sessions/{session_id}/commands/{command_id}

Check the execution status and retrieve the response of a specific command. This endpoint utilizes a smart long-polling mechanism (up to a set timeout, generally 15-30 seconds). If the command's status is "pending" or "running", it will hold the connection open, returning immediately when the status changes to "done" or "failed".

If the response data (e.g., large HTML snapshot or image data) exceeds internal limits, it is offloaded to the cloud and you'll receive an offloaded_data_url instead of inline JSON data in the response object.

Path Parameters:

  • session_id (string): The unique identifier of the session.
  • command_id (string): The unique identifier of the command (returned from the execution request).

Response Example (Success):

json
{
  "success": true,
  "command_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "session_id": "8a7b6c5d-4e3f-2g1h-9i8j-7k6l5m4n3o2p",
  "status": "done",
  "created_at": "2026-05-01T12:04:58Z",
  "finished_at": "2026-05-01T12:05:15Z",
  "response": {
    "commands": [
        {
            "step": 0,
            "data": {
                "url": "about:blank"
            },
            "success": true,
            "command": "get_url"
        },
        {
            "step": 1,
            "data": {
                "url": "https://example.com"
            },
            "success": true,
            "command": "open_url"
        }
    ]
  }
}

Response Example (Failure):

json
{
  "success": true,
  "command_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "session_id": "8a7b6c5d-4e3f-2g1h-9i8j-7k6l5m4n3o2p",
  "status": "failed",
  "error_name": "InvalidParams",
  "error_message": "run_js() missing 1 required positional argument: 'js_code'",
  "created_at": "2026-05-01T12:04:58Z",
  "finished_at": "2026-05-01T12:05:05Z",
  "response": {
    "commands": [
      {
        "step": 0,
        "success": false,
        "command": "run_js",
        "error_name": "InvalidParams",
        "error_message": "run_js() missing 1 required positional argument: 'js_code'"
      }
    ]
  }
}