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

# Custom proxies

> Route a session's browser traffic through your own HTTP or HTTPS proxy.

Pass `proxy` to `POST /v1/session` to use your own proxy for the session's lifetime. The feature must be enabled for your account. See [Use your own proxy](https://docs.tilion.dev/guides/custom-proxy.md) for runnable examples.

The `proxy` field is optional and applies only to the session created with it. Omit it to use Tilion's exits, IP rotation, automatic recovery, and geo options as usual.

## Request fields

All three fields are required when `proxy` is provided.

| Field | Type | Requirements |
| - | - | - |
| `proxy.server` | string | `http://host:port` or `https://host:port`. Include a port. Paths and credentials in the URL are not allowed. |
| `proxy.username` | string | Proxy username. |
| `proxy.password` | string | Proxy password. It is never stored, logged, or returned, including in error responses. |

```json theme={"dark"}
{
  "proxy": {
    "server": "http://proxy.example.com:8080",
    "username": "your-proxy-user",
    "password": "your-proxy-password"
  }
}
```

The response is the standard [session object](https://docs.tilion.dev/sessions/sessions.md), including `session_id` and `connect_url`. REST and CDP control work as usual.

## Routing and billing

Tilion tests one connection through the proxy before starting the browser. The proxy host must resolve to a public internet address. HTTP and HTTPS proxies are supported; SOCKS5 is not supported.

All browser traffic uses this proxy for the session's lifetime. Tilion does not rotate the exit or switch to another exit during automatic recovery. Your proxy provider controls the exit IP. A sticky proxy keeps its assigned IP according to the provider's settings.

Traffic through your proxy does not count against your Tilion premium proxy allowance. Browser time is billed as usual.

## Conflicting fields

Do not combine `proxy` with `residential: false`, `proxy_type`, `geo`, `exit_id`, `exit_region`, `site_check: true`, `full_browser`, or `kiosk`. A conflicting request returns `400 customer_proxy_conflict`, with the conflicting names in `fields`.

## Errors

| HTTP status | Error body | Meaning |
| - | - | - |
| 422 | Validation list in `detail` | The `proxy` object is missing `server`, `username`, or `password`, or `proxy` is not an object. The response identifies the field without echoing the password. |
| 400 | `customer_proxy_invalid` | The server URL is not `http(s)://host:port`, or a credential string is empty or malformed. |
| 400 | `customer_proxy_auth_failed` | The proxy rejected the username or password with HTTP 407. |
| 400 | `customer_proxy_not_public` | The proxy host resolves to a private or internal address. |
| 400 | `customer_proxy_conflict` | The request includes conflicting session fields. `fields` lists their names. |
| 400 | `customer_proxy_disabled` | Custom proxies are not enabled for the account. |
| 502 | `customer_proxy_unreachable` | The proxy did not respond, or its TLS connection failed. |
| 502 | `customer_proxy_refused` | The proxy responded but refused to open the tunnel. |
| 409 | `customer_proxy_session` | `POST /v1/session/{id}/rotate-ip` was called on a custom-proxy session. Change the exit through your proxy provider. |


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