Create a browser

POST /v1/session creates an isolated Chrome instance. An empty JSON body uses the defaults. Set TILION_API_KEY before running an example.

import os
import uuid
import requests

response = requests.post(
    "https://back.tilion.dev/v1/session",
    headers={
        "Authorization": f"Bearer {os.environ['TILION_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"ttl": 600, "idle_timeout": 120}, timeout=200,
)
response.raise_for_status()
print(response.json()["session_id"])

import { randomUUID } from "node:crypto";

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": randomUUID(),
  },
  body: JSON.stringify({ ttl: 600, idle_timeout: 120 }),
  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 https://back.tilion.dev/v1/session \
  -H "Authorization: Bearer $TILION_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"ttl": 600, "idle_timeout": 120}'

The response includes session_id, state, connect_url, and playwright_url. These examples leave the browser running. Export its ID for the other guides:

export TILION_SESSION_ID="sess_..."

Configure the session

Field	Behavior
`ttl`	Maximum session lifetime in seconds, subject to your plan’s limit.
`idle_timeout`	Ends an inactive session. Browser actions and CDP activity reset this timer. Reading session metadata does not.
`region`	Browser region from `GET /v1/regions`.
`residential`	Enables a residential exit, billed as premium egress.
`geo`	Requests an exit location when residential routing is enabled.
`full_browser`	Requests a visible Chrome desktop for VNC.

To request a US residential exit, use this creation body:

{"residential": true, "geo": {"country": "us"}}

Check geo_applied and geo_unsupported in the response to confirm which location settings were applied. To route browser traffic through your own provider, see Use your own proxy. Custom proxies use a separate proxy object and cannot be combined with geo or Tilion exit-selection fields.

For retries, reuse the original Idempotency-Key value. Generate a new value for each new session. The server retains this association for about an hour.

Close the browser

curl --fail-with-body -X DELETE \
  "https://back.tilion.dev/v1/session/$TILION_SESSION_ID" \
  -H "Authorization: Bearer $TILION_API_KEY"

Deletion returns 204. See the session reference for all creation fields and the quickstart for automatic cleanup.

Start

Read and interact

Browser tools

Account

Create a browser

Configure the session

Close the browser

​Configure the session

​Close the browser

Configure the session

Close the browser