Viewports

​

Overview

A viewport defines the visible area of a web page in a browser window. While setting a custom viewport is optional in Browserbase, it can be helpful for specific use cases — such as visual testing, screenshot generation, or automations that rely on precise layout behavior.

By default, Browserbase generates realistic, randomized viewports to enhance stealth and reduce detection. However, if your automation requires a consistent viewport size (e.g., for comparing screenshots across sessions), you can select from a predefined set of supported dimensions.

​

Supported Viewport Sizes

When creating a session, you can choose from the following approved viewport dimensions. These values are optimized for reliability and stealth, and are the only sizes currently supported.

​

Desktop Viewports

​

Mobile Viewports

​

How to Set a Viewport in Your Session

Use the viewport and fingerprint.screen fields when creating a session to specify the desired width and height. Below are examples in both Node.js and Python SDKs.

import Browserbase from "@browserbasehq/sdk";

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

async function createBasicStealthSession() {
  const session = await bb.sessions.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
    browserSettings: {
      fingerprint: {
        screen: {
          maxWidth: 1920,
          maxHeight: 1080,
          minWidth: 1024,
          minHeight: 768,
        }
      },
      viewport: {
        width: 1920,
        height: 1080,
      },
    },
  });
  console.log(`Session URL: https://browserbase.com/sessions/${session.id}`);
  return session;
}

const session = createBasicStealthSession();

import Browserbase from "@browserbasehq/sdk";

const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

async function createBasicStealthSession() {
  const session = await bb.sessions.create({
    projectId: process.env.BROWSERBASE_PROJECT_ID!,
    browserSettings: {
      fingerprint: {
        screen: {
          maxWidth: 1920,
          maxHeight: 1080,
          minWidth: 1024,
          minHeight: 768,
        }
      },
      viewport: {
        width: 1920,
        height: 1080,
      },
    },
  });
  console.log(`Session URL: https://browserbase.com/sessions/${session.id}`);
  return session;
}

const session = createBasicStealthSession();

from browserbase import Browserbase
import os

bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

def createBasicStealthSession():
    session = bb.sessions.create(
        project_id=os.environ["BROWSERBASE_PROJECT_ID"],
        browser_settings={
            "fingerprint": {
                "screen": {
                    "maxWidth": 1920,
                    "maxHeight": 1080,
                    "minWidth": 1024,
                    "minHeight": 768,
                },
            },
            "viewport": {
                "width": 1920,
                "height": 1080,
            },
        },
    )
    print(f"Session URL: https://browserbase.com/sessions/{session.id}")
    return session

session = createBasicStealthSession()

Custom viewports are a powerful feature when precision matters — whether you’re automating mobile interactions, capturing consistent screenshots, or testing responsive layouts. For most use cases, Browserbase’s default viewport generation provides the best balance of stealth and reliability. Only configure a specific viewport if your use case requires it.

For a full list of session options and configuration fields, check out the API reference for creating a session.