Third-Party Proxy

BrowserCat allows you to use a custom proxy server with any browser or automation library we support.

Use this feature when you need to make requests from a specific region or IP range. It’s very handy for web scraping jobs.

Before you begin

BrowserCat is deployed world-wide across a number of geographic regions. While we typically route your request to the nearest server for performance, you can manually target a different region.

Before evaluating third-party proxies, try using our region config to see if it meets your needs. It’s cost-effective and fast, although it may not be as reliable as a dedicated proxy.

Configure your proxy

As with all BrowserCat browser config, you can pass your proxy configuration using the BrowserCat-Opts header.

We’ll use the proxy key within this object to define the proxy configuration.

Here’s an example of how you might define this header:

const headers = {
  'browsercat-opts': JSON.stringify({
    proxy: {
      server: 'http://proxy.example.com:8080',
      username: 'proxycat',
      password: '<PASSWORD>',
      bypass: 'example.com',
    },
  }),
};

headers = {
    'browsercat-opts': json.dumps({
        'proxy': {
            'server': 'http://proxy.example
            'username': 'proxycat',
            'password': '<PASSWORD>',
            'bypass': 'example.com'
        }
    })
}

Let’s break down the proxy configuration options:

server (required): The URL of your proxy server.
username (optional): The username for proxy authentication.
password (optional): The password for proxy authentication.
bypass (optional): Comma-separated list of domain patterns to bypass proxy for. Matches on ends-with. For example, api.google.com, example.org, .net. Use this setting to save bandwidth.

Playwright request

Let’s use our proxy config in a Playwright request:

import * as pw from 'playwright';

const bcatUrl = 'wss://api.browsercat.com/connect';
const browser = await pw.chromium.connect(bcatUrl, {
  headers: {
    'api-key': '<YOUR_API_KEY>',
    'browsercat-opts': JSON.stringify({
      proxy: {
        server: 'http://proxy.example.com:8080',
        username: 'proxycat',
        password: '<PASSWORD>',
        bypass: 'example.com',
      },
    }),
  },
});
await browser.close();

import asyncio
from playwright.async_api import async_playwright, Playwright

bcatUrl = 'wss://api.browsercat.com/connect'

async def run():
    async with async_playwright() as pw:
        browser = await pw.chromium.connect(bcatUrl, headers={
            'Api-Key': '<YOUR_API_KEY>'
            'browsercat-opts': json.dumps({
                'proxy': {
                    'server': 'http://proxy.example
                    'username': 'proxycat',
                    'password': '<PASSWORD>',
                    'bypass': 'example.com'
                }
            })
        })
        await browser.close()

asyncio.get_event_loop().run_until_complete(run())

Puppeteer request

Let’s see our headers in a Puppeteer request:

import puppeteer from 'puppeteer-core';

const bcatUrl = 'wss://api.browsercat.com/connect';
const browser = await puppeteer.connect({
  browserWSEndpoint: bcatUrl,
  headers: {
    'api-key': '<YOUR_API_KEY>',
    'browsercat-opts': JSON.stringify({
      proxy: {
        server: 'http://proxy.example.com:8080',
        username: 'proxycat',
        password: '<PASSWORD>',
        bypass: 'example.com',
      },
    }),
  },
});
await browser.close();

import asyncio
from pyppeteer import connect

bcatUrl = 'wss://api.browsercat.com/connect'

async def run():
    browser = await connect({
        'browserWSEndpoint': bcatUrl,
        'headers': {
            'api-key': '<YOUR_API_KEY>',
            'browsercat-opts': json.dumps({
                'proxy': {
                    'server': 'http://proxy.example
                    'username': 'proxycat',
                    'password': '<PASSWORD>',
                    'bypass': 'example.com'
                }
            })
        }
    })
    await browser.close()

asyncio.get_event_loop().run_until_complete(run())