Proxy Routes

Proxy routes let a session send traffic for some hosts straight out instead of through its proxy, or keep some hosts on the proxy while the rest go direct. Use them when only part of what a session loads needs the proxy, for example to reach your own APIs or a CDN directly while the pages you browse go through the proxy.

Proxy routes are enabled for teams on request. Contact us at info@hyperbrowser.ai to get access. Until they’re enabled for your team, proxyRoutes is ignored and all of the session’s traffic uses the proxy.

Create a session with proxy routes

Proxy routes need a session proxy: set useProxy, with Hyperbrowser’s managed proxy, a custom proxyServer, or a staticIpId. Then pass proxyRoutes (proxy_routes in Python). Each route has a match, which is one pattern or a list of them, and a proxy:

"direct" sends matching traffic straight out of the browser’s machine.
"default" sends matching traffic through the session’s proxy.

import { Hyperbrowser } from "@hyperbrowser/sdk";

const client = new Hyperbrowser({ apiKey: process.env.HYPERBROWSER_API_KEY });

const session = await client.sessions.create({
  useProxy: true,
  proxyRoutes: [
    { match: "login.example.com", proxy: "default" },
    { match: ["*.example.com", "cdn.example.net"], proxy: "direct" },
  ],
});

import os
from hyperbrowser import Hyperbrowser

client = Hyperbrowser(api_key=os.environ["HYPERBROWSER_API_KEY"])

session = client.sessions.create({
    "use_proxy": True,
    "proxy_routes": [
        {"match": "login.example.com", "proxy": "default"},
        {"match": ["*.example.com", "cdn.example.net"], "proxy": "direct"},
    ],
})

curl -X POST https://api.hyperbrowser.ai/api/session \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "useProxy": true,
    "proxyRoutes": [
      {"match": "login.example.com", "proxy": "default"},
      {"match": ["*.example.com", "cdn.example.net"], "proxy": "direct"}
    ]
  }'

In this example, login.example.com goes through the proxy, every other subdomain of example.com and cdn.example.net go direct, and all other hosts, including example.com itself, go through the proxy.

How routes match

A pattern is a hostname such as example.com, *.example.com for every subdomain of example.com but not example.com itself, or * for every host. To cover a domain and its subdomains, list both: ["example.com", "*.example.com"].
A pattern matches the host on any port. URLs, ports, and IP addresses aren’t accepted as patterns; only * matches a host that is reached by IP address.
You can write internationalized hostnames in Unicode or in punycode.
Routes are checked in order, and the first route that matches a host decides. Hosts that no route matches go through the proxy.

To send everything direct except a few hosts, list those hosts with "default" first and finish with { "match": "*", "proxy": "direct" }.

Limits

A session can have up to 32 routes and 128 patterns across all of its routes.
You set routes when you create a session with the sessions API. Scrape, crawl, extract, and agent task requests don’t accept proxyRoutes.
Proxy routes can’t be combined with a network policy: allowInternetAccess: false, allowOut, or denyOut.

Status	Cause
`400`	A pattern or route is invalid, the session has no proxy, a network policy is set, the request is a scrape, crawl, extract, or agent task, or another session option can’t be combined with proxy routes

Proxy Configuration

Managed and custom proxies, and location targeting

Static IPs

Use dedicated IP addresses

Get Started

Browser Sessions

Session Configuration

Web API

Agents

HyperAgent Usage

Scraping

Integrations

Create a session with proxy routes

How routes match

Limits

Proxy Configuration

Static IPs

​Create a session with proxy routes

​How routes match

​Limits

​Related Features

Proxy Configuration

Static IPs

Create a session with proxy routes

How routes match

Limits

Related Features