> ## Documentation Index
> Fetch the complete documentation index at: https://docs.searchcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Browser Session

> Create or navigate a Browserbase browser session for live website scanning visualization

Public endpoint used on the marketing website to show a live browser scanning animation. Uses Browserbase API with Playwright for fast, reliable browser sessions.

<Note>
  This is a **public endpoint** - no authentication required. Used on the
  searchcompany.ai landing page ranking flow.
</Note>

## Request Body

<ParamField body="url" type="string">
  Website URL to navigate to. If omitted, creates a pre-warmed session without navigation.
</ParamField>

<ParamField body="region" type="string" default="us-west-2">
  Browserbase region for the session. Valid values: `us-west-2`, `us-east-1`, `eu-central-1`, `ap-southeast-1`
</ParamField>

<ParamField body="viewport" type="object">
  Optional custom viewport dimensions

  <Expandable title="viewport properties">
    <ParamField body="width" type="integer">
      Viewport width in pixels
    </ParamField>

    <ParamField body="height" type="integer">
      Viewport height in pixels
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="session_id" type="string">
  If provided, navigates an existing session instead of creating a new one
</ParamField>

## Response

<ResponseField name="session_id" type="string">
  Unique identifier for the browser session
</ResponseField>

<ResponseField name="live_url" type="string">
  URL to embed the live browser view (iframe-compatible)
</ResponseField>

## How It Works

1. **Pre-warm (no URL)** - Creates a new Browserbase session and returns immediately
2. **Navigate (with URL)** - Navigates an existing session to the URL in the background
3. **Session Reuse** - Sessions are cached per client IP + viewport for 5 minutes

The endpoint supports a two-phase flow:

1. First call without URL to pre-warm the session (fast)
2. Second call with URL and session\_id to start navigation

<RequestExample>
  ```bash Pre-warm Session theme={null}
  curl -X POST "https://searchcompany-main.up.railway.app/api/browser-session" \
    -H "Content-Type: application/json" \
    -d '{
      "region": "us-west-2",
      "viewport": {"width": 1280, "height": 720}
    }'
  ```

  ```bash Navigate Session theme={null}
  curl -X POST "https://searchcompany-main.up.railway.app/api/browser-session" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com",
      "session_id": "abc123-session-id"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "session_id": "abc123-def456-ghi789",
    "live_url": "https://www.browserbase.com/devtools-fullscreen/abc123?navbar=false"
  }
  ```
</ResponseExample>

## Usage on Landing Page

```typescript theme={null}
// 1. Pre-warm session when user starts typing
const { session_id, live_url } = await createBrowserSession(
  undefined, // no URL yet
  { width: 1280, height: 720 }
);

// 2. Show live_url in iframe immediately
iframeRef.src = live_url;

// 3. Navigate when user submits URL
await createBrowserSession(userUrl, undefined, session_id);
```

## Rate Limiting

* **60 requests/minute** per IP address