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

# Use your own proxy

> Create a browser session that routes traffic through your proxy provider.

Custom proxies must be enabled for your account. Set your Tilion API key and proxy credentials in the terminal where you run the example:

```bash theme={"dark"}
export TILION_API_KEY="ph_live_..."
export PROXY_SERVER="http://proxy.example.com:8080"
export PROXY_USERNAME="your-proxy-user"
export PROXY_PASSWORD="your-proxy-password"
```

Use an HTTP or HTTPS proxy with a public hostname or IP address and an explicit port. Put credentials in the separate fields, with no path or credentials in `PROXY_SERVER`.

## Create the session

Generate an idempotency key separately with `uuidgen`. Run this once for each new session:

```bash theme={"dark"}
export TILION_IDEMPOTENCY_KEY="$(uuidgen)"
```

The request examples below read this key from your environment. To retry the same creation request, rerun only the request example with the same key and body. Keep the original value if you switch terminals. Generate a new key when you want a new session.

The Python example requires `requests`. Run the Node.js example as an `.mjs` file with Node 20 or later. The curl example requires `jq`.

```python Python theme={"dark"}
import os
import requests

response = requests.post(
    "https://back.tilion.dev/v1/session",
    headers={
        "Authorization": f"Bearer {os.environ['TILION_API_KEY']}",
        "Idempotency-Key": os.environ["TILION_IDEMPOTENCY_KEY"],
    },
    json={"proxy": {
        "server": os.environ["PROXY_SERVER"],
        "username": os.environ["PROXY_USERNAME"],
        "password": os.environ["PROXY_PASSWORD"],
    }},
    timeout=200,
)
response.raise_for_status()
print(response.json()["session_id"])
```

```javascript Node.js theme={"dark"}
const idempotencyKey = process.env.TILION_IDEMPOTENCY_KEY;
if (!idempotencyKey) throw new Error("Set TILION_IDEMPOTENCY_KEY before running this example");

const response = await fetch("https://back.tilion.dev/v1/session", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TILION_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey,
  },
  body: JSON.stringify({ proxy: {
    server: process.env.PROXY_SERVER,
    username: process.env.PROXY_USERNAME,
    password: process.env.PROXY_PASSWORD,
  } }),
  signal: AbortSignal.timeout(200_000),
});
if (!response.ok) throw new Error(await response.text());
console.log((await response.json()).session_id);
```

```bash curl theme={"dark"}
curl --fail-with-body --silent --show-error \
  https://back.tilion.dev/v1/session \
  -H "Authorization: Bearer $TILION_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${TILION_IDEMPOTENCY_KEY:?Set TILION_IDEMPOTENCY_KEY first}" \
  -d "$(jq -n '{proxy: {
    server: env.PROXY_SERVER,
    username: env.PROXY_USERNAME,
    password: env.PROXY_PASSWORD
  }}')"
```

Tilion tests the proxy before starting the browser. A successful request returns the standard session object. These examples leave the session running. Set `TILION_SESSION_ID` to its `session_id`, then [read a page](https://docs.tilion.dev/guides/read-page.md) or [connect Playwright](https://docs.tilion.dev/guides/playwright.md).

The server retains the idempotency-key association for about an hour. See [session creation](https://docs.tilion.dev/sessions/sessions.md#post-v1session) for retry behavior.

## Keep the proxy for the session

All browser traffic goes through your proxy. Tilion's recovery does not switch it to another exit, and `/rotate-ip` returns `409 customer_proxy_session`. Manage IP changes through your proxy provider.

Omit `residential: false`, `proxy_type`, `geo`, `exit_id`, `exit_region`, `site_check: true`, `full_browser`, and `kiosk` when using a custom proxy. SOCKS5 is not supported.

Traffic through your proxy does not use your Tilion premium proxy allowance. Browser time is billed until the session ends.

## Close the session

```bash theme={"dark"}
curl --fail-with-body -X DELETE \
  "https://back.tilion.dev/v1/session/$TILION_SESSION_ID" \
  -H "Authorization: Bearer $TILION_API_KEY"
```

See the [custom proxy reference](https://docs.tilion.dev/sessions/custom-proxy.md) for validation, authentication, and connection errors.


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