Use your own proxy

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

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:

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.

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"])

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);

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 or connect Playwright. The server retains the idempotency-key association for about an hour. See session creation 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

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 for validation, authentication, and connection errors.

Start

Read and interact

Browser tools

Account

Use your own proxy

Create the session

Keep the proxy for the session

Close the session

​Create the session

​Keep the proxy for the session

​Close the session

Create the session

Keep the proxy for the session

Close the session