Custom proxies

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

{
  "proxy": {
    "server": "http://proxy.example.com:8080",
    "username": "your-proxy-user",
    "password": "your-proxy-password"
  }
}

The response is the standard session object, 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.

Get started

Account

Sessions

Reading pages

Automation

MCP

Custom proxies

Request fields

Routing and billing

Conflicting fields

Errors

​Request fields

​Routing and billing

​Conflicting fields

​Errors

Request fields

Routing and billing

Conflicting fields

Errors