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

# Proxy Routes

> Choose which hosts a session reaches through its proxy and which it reaches directly

Proxy routes let a session send traffic for some hosts straight out instead of through its [proxy](/docs/sessions/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.

<Note>
  Proxy routes are enabled for teams on request. Contact us at [info@hyperbrowser.ai](mailto: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.
</Note>

## 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.

<CodeGroup>
  ```typescript Node.js theme={null}
  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" },
    ],
  });
  ```

  ```python Python theme={null}
  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"},
      ],
  })
  ```

  ```bash cURL theme={null}
  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"}
      ]
    }'
  ```
</CodeGroup>

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 |

## Related Features

<CardGroup cols={2}>
  <Card title="Proxy Configuration" icon="globe" href="/docs/sessions/proxy">
    Managed and custom proxies, and location targeting
  </Card>

  <Card title="Static IPs" icon="map-pin" href="/docs/sessions/static-ips">
    Use dedicated IP addresses
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.