Core Concepts

The mental model behind Chaser: sessions, fingerprints, CDP, billing, and how they connect.

Sessions

A session is a browser instance with a finite lifetime. You create it, connect to it over CDP, use it, and delete it (or let it expire).

creating → ready → closed
                   → error

• creating — the session is being provisioned. Wait for ready.
• ready — the CDP URL is live. Connect and automate.
• closed — the session ended. Check ended_reason to understand why.
• error — the session failed before becoming ready. No charge.

Sessions are isolated. Each one has its own cookies, localStorage, cache, and IP address. Cross-session data leakage is not possible.

The CDP connection

Chaser exposes each session through a standard Chrome DevTools Protocol WebSocket endpoint:

wss://cdp.chaser.sh/sessions/{session_id}

This is the same protocol Playwright and Puppeteer use to talk to a local browser. The difference is that the browser is remote. Your CDP client opens a WebSocket, sends commands, and receives events — exactly as it would against localhost.

Use chromium.connectOverCDP(cdpUrl) (Playwright/patchright) or puppeteer.connect({ browserWSEndpoint: cdpUrl }). Do not use browserType.launch() — that would start a local browser, which is not what you want.

The session has a default browser context. Use browser.contexts()[0] to access it. Creating additional contexts is not supported.

Profiles and fingerprints

A profile is a base configuration label that determines the pool of fingerprints sessions are drawn from. The default profile covers the most common use cases — you don’t need to specify one unless you have specific requirements.

Each session gets a unique fingerprint from a corpus of thousands of real browser captures. Every signal — user-agent, client hints, canvas, WebGL, audio, fonts, screen metrics, JA4 TLS signature — is drawn from the same captured device, so all signals are internally consistent. The residential egress IP matches the fingerprint’s claimed geography and ISP type.

You don’t configure individual signals. You don’t manage fingerprint rotation. Each session is different, and each one looks real.

Egress and proxies

Every session routes its traffic through a residential proxy. The proxy is included in the $5/GB price — there is no separate proxy fee, no per-GB proxy surcharge, and no proxy configuration in your code.

The proxy IP matches the profile’s claimed geography and ISP type.

Billing

You prepay into a workspace balance. Egress is metered in bytes and deducted from that balance at $5/GB.

charge = bytes_total × $5 / 1,000,000,000

• bytes_total = bytes_up + bytes_down for every session under the workspace
• Billed at the end of each session (when it closes or expires)
• No charge for sessions that end in error status before becoming ready
• No idle charges — you pay for data transferred, not time connected

Check your balance and usage:

$
curl -s https://api.chaser.sh/v1/usage \
>
  -H "Authorization: Bearer $CHASER_KEY" | jq

Session lifecycle in detail

1. Create — POST /v1/sessions. Returns immediately with status: "creating".
2. Provision — Chaser allocates the browser, applies the fingerprint profile, and connects the residential egress. Typically 15–25 seconds.
3. Ready — status transitions to "ready". The cdp_url is live.
4. Use — Connect over CDP, automate, screenshot, watch.
5. End — One of:
   • Client delete — you call DELETE /v1/sessions/{id}
   • TTL expiry — the session reaches its expires_at timestamp
   • Idle expiry — no CDP connection for an extended period
   • Error — infrastructure failure (no charge)

Limits

When you hit a limit, the API returns a 429 with a retry_after_seconds field.