Quickstart

If you use an AI coding assistant, paste this prompt into Cursor, Claude Code, or Windsurf:

Read https://docs.tilion.dev/llms.txt and use the Tilion API to
create a browser session, attach Playwright over CDP, open
example.com, print the title, and release the session in a
finally block.

1. Create an account

The free plan includes 10 browser hours and 500 actions per month with 3 concurrent sessions. It requires no credit card.

2. Get an API key

In the dashboard, open API Keys and create one. Keys look like ph_live_…. The key is shown once at creation and stored hashed, so copy it immediately; it cannot be retrieved later. If you lose it, revoke it and mint a new one. Keep keys server-side, because a key grants full control of your browser sessions.

export TILION_API_KEY="ph_live_your_key_here"

3. Create a session

curl -X POST https://api.tilion.dev/v1/session \
  -H "Authorization: Bearer $TILION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "session_id": "sess_1f68f2e37b7d4e339112b906a66200d4",
  "state": "ready",
  "mode": "ephemeral",
  "region": null,
  "connect_url": "wss://api.tilion.dev:9223/v1/session/sess_1f68.../cdp?token=...",
  "connect_expires_in": 300
}

The response includes connect_url, so you can attach immediately with no second call.

Read this before you build. connect_url is returned only by this call and by /connect. Reading a session back with GET /v1/session/{id} returns connect_url: null by design. See Connecting a browser for the reasoning and what to do instead.

4. Attach Playwright

Tilion speaks the Chrome DevTools Protocol, so any CDP client works unchanged.

import { chromium } from 'playwright-core';

const res = await fetch('https://api.tilion.dev/v1/session', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TILION_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
});
const session = await res.json();

const browser = await chromium.connectOverCDP(session.connect_url);
const context = browser.contexts()[0];
const page = context.pages()[0];

await page.goto('https://example.com');
console.log(await page.title());

await browser.close();

await fetch(`https://api.tilion.dev/v1/session/${session.session_id}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.TILION_API_KEY}` },
});

import os, requests
from playwright.sync_api import sync_playwright

key = os.environ["TILION_API_KEY"]
h = {"Authorization": f"Bearer {key}", "Content-Type": "application/json"}

session = requests.post("https://api.tilion.dev/v1/session", headers=h, json={}).json()

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(session["connect_url"])
    page = browser.contexts[0].pages[0]
    page.goto("https://example.com")
    print(page.title())
    browser.close()

requests.delete(
    f"https://api.tilion.dev/v1/session/{session['session_id']}", headers=h
)

A session already has one browser context with one page open. Use those rather than calling newContext() / newPage(), or you will pay for a second renderer you do not need.

5. Release the session

Sessions are billed while they exist, so release them explicitly:

curl -X DELETE https://api.tilion.dev/v1/session/$SESSION_ID \
  -H "Authorization: Bearer $TILION_API_KEY"

The call returns 204 No Content. Every session also has an idle timeout and is reclaimed automatically, but do not rely on that for cost control. Always release in a finally block.

Fetch a page without driving the browser

If you only need page content, skip the CDP client. Create a session as above, then ask for the page in one request:

curl -X POST https://api.tilion.dev/v1/fetch \
  -H "Authorization: Bearer $TILION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "'"$SESSION_ID"'", "url": "https://example.com"}'

The full options are on the Fetch page.

Next steps

Connecting a browser covers CDP, tokens, and reconnecting.
Sessions covers lifecycle, modes, and timeouts.
Fetch covers getting page content without driving a browser.
Errors and Limits cover every status code, quota, and rate limit.

Get started

MCP

Sessions

Fetch & jobs

Content

Agent & tasks

Live view & recordings

Account

Reference

1. Create an account

2. Get an API key

3. Create a session

4. Attach Playwright

5. Release the session

Fetch a page without driving the browser

Next steps

​1. Create an account

​2. Get an API key

​3. Create a session

​4. Attach Playwright

​5. Release the session

​Fetch a page without driving the browser

​Next steps

1. Create an account

2. Get an API key

3. Create a session

4. Attach Playwright

5. Release the session

Fetch a page without driving the browser

Next steps