> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stophy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser sessions

> Open a cloud browser, drive it over CDP with Playwright or Puppeteer or run code in it, then close it. $0.06 per hour open, plus traffic per GB.

A browser session is a real browser in the cloud that stays open between your calls. You pay for the time it is open, so close every session you open.

## Make a request

Get an API key in the [Quickstart](https://docs.stophy.dev/quickstart). Browser sessions need an API key. This request opens a session that lives for at most 5 minutes and closes itself after 60 seconds with no calls.

```bash cURL theme={null}
curl -X POST https://api.stophy.dev/v1/browser \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ttl": 300,
    "activityTtl": 60
  }'
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/browser", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ ttl: 300, activityTtl: 60 }),
});
const session = await response.json();
console.log(session.id, session.cdpUrl);
```

```python Python theme={null}
import os

import requests

response = requests.post(
    "https://api.stophy.dev/v1/browser",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={"ttl": 300, "activityTtl": 60},
)
session = response.json()
print(session["id"], session["cdpUrl"])
```

## Read the response

Keep `id`: every other call on the session uses it. This real response is cut to the fields you need first. The tokens in the links are cut.

```json theme={null}
{
  "success": true,
  "id": "f7db13f1-398b-4f20-8c12-825715c2ffd1",
  "status": "active",
  "createdAt": "2026-11-17T18:14:38.043Z",
  "timeoutAt": "2026-11-17T18:15:38.043Z",
  "expiresAt": "2026-11-17T18:19:38.038Z",
  "metadata": {},
  "networkPolicyId": null,
  "cdpUrl": "wss://api.stophy.dev/v1/interact/f7db13f1-398b-4f20-8c12-825715c2ffd1/cdp?token=…",
  "liveViewUrl": "https://api.stophy.dev/v1/interact/f7db13f1-398b-4f20-8c12-825715c2ffd1/live#…",
  "interactiveLiveViewUrl": "https://api.stophy.dev/v1/interact/f7db13f1-398b-4f20-8c12-825715c2ffd1/live#…",
  "recordingStatus": "none",
  "costUsd": 0,
  "requestId": "6a40d94c-7192-41df-b4ba-6c3aea8c76ed"
}
```

`cdpUrl` is where Playwright or Puppeteer connects. `liveViewUrl` lets you watch the session, and `interactiveLiveViewUrl` lets you watch and control it. `timeoutAt` is when the session closes by itself if nothing happens. Opening a session costs nothing. The time and traffic are billed when it closes.

## Connect over CDP

Any client that speaks the Chrome DevTools Protocol can drive the session. Connect to `cdpUrl`, and use the page that is already open.

```typescript Playwright theme={null}
import { chromium } from "playwright-core";

const headers = {
  Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
  "Content-Type": "application/json",
};

const opened = await fetch("https://api.stophy.dev/v1/browser", {
  method: "POST",
  headers,
  body: JSON.stringify({ ttl: 300, activityTtl: 60 }),
});
const session = await opened.json();

const browser = await chromium.connectOverCDP(session.cdpUrl);
const context = browser.contexts()[0] ?? (await browser.newContext());
const page = context.pages()[0] ?? (await context.newPage());
await page.goto("https://example.com");
console.log(await page.title());
await browser.close();

const closed = await fetch(`https://api.stophy.dev/v1/browser/${session.id}`, {
  method: "DELETE",
  headers,
});
console.log(await closed.json());
```

```typescript Puppeteer theme={null}
import puppeteer from "puppeteer-core";

const headers = {
  Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
  "Content-Type": "application/json",
};

const opened = await fetch("https://api.stophy.dev/v1/browser", {
  method: "POST",
  headers,
  body: JSON.stringify({ ttl: 300, activityTtl: 60 }),
});
const session = await opened.json();

const browser = await puppeteer.connect({ browserWSEndpoint: session.cdpUrl });
const [page = await browser.newPage()] = await browser.pages();
await page.goto("https://example.com");
console.log(await page.title());
await browser.disconnect();

const closed = await fetch(`https://api.stophy.dev/v1/browser/${session.id}`, {
  method: "DELETE",
  headers,
});
console.log(await closed.json());
```

The Playwright example printed `Example Domain`, then the closing bill. Disconnecting does not close the session: it keeps running, and billing, until you send `DELETE` or it times out. The link carries a token for this session, so keep it private. Activity on the CDP connection counts as a call for `activityTtl`.

You do not need a CDP client to use a session. [Run code or a prompt](https://docs.stophy.dev/browser/execute.md) in it with one HTTP call.

## Set how long it lives

| Field | Type | Default | Effect |
| - | - | - | - |
| `ttl` | `number` | `600` | The most seconds the session can live, from 30 to 21,600. |
| `activityTtl` | `number` | `300` | Seconds the session waits with no call before it closes, from 10 to 21,600. Each call on the session moves `timeoutAt` forward. |

The session closes at the earlier of `expiresAt` (`ttl` after it opened) and the idle limit. You are billed for the time it was open either way.

## Close a session

Send `DELETE` as soon as you are done. This is when the time and traffic are billed.

```bash cURL theme={null}
SESSION_ID="<the id your session returned>"
curl -X DELETE https://api.stophy.dev/v1/browser/$SESSION_ID \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

```typescript TypeScript theme={null}
const sessionId = "<the id your session returned>";
const response = await fetch(`https://api.stophy.dev/v1/browser/${sessionId}`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}` },
});
console.log(await response.json());
```

```python Python theme={null}
import os

import requests

session_id = "<the id your session returned>"
response = requests.delete(
    f"https://api.stophy.dev/v1/browser/{session_id}",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
)
print(response.json())
```

This real session was open for 34 seconds.

```json theme={null}
{
  "success": true,
  "recordingStatus": "none",
  "sessionDurationMs": 34117,
  "proxyBytes": 34603,
  "exitBytes": {
    "managed": 34603,
    "direct": 0,
    "custom": 0
  },
  "creditsBilled": 2,
  "costUsd": 0.004,
  "creditsUsed": 2,
  "requestId": "2e9de582-5085-46f4-a5d6-907b4279e406"
}
```

`sessionDurationMs` is how long the session was open. `proxyBytes` is all its traffic, and `exitBytes` splits it by how the session reached the web, because each kind has its own price. See [Network location](https://docs.stophy.dev/browser/network-location.md). `costUsd` is the bill. `creditsBilled` and `creditsUsed` are the older fields for the same amount, in steps of \$0.002. Closing a session that is already closed returns the same bill and charges nothing more.

## Read and list sessions

`GET /v1/browser/{session_id}` returns one session, and is free. A running session also lists its `downloads` and `uploads`. After it closes, the same call shows what it cost: `proxyUsedMb`, `browserCostUsd` and `proxyCostUsd`.

```bash theme={null}
curl https://api.stophy.dev/v1/browser/$SESSION_ID \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

This real closed session shows the bill split in two. The links are cut.

```json theme={null}
{
  "success": true,
  "id": "96aa4901-52b9-440a-9dab-5df9b53a5387",
  "status": "destroyed",
  "finishedAt": "2026-11-17T18:17:01.010Z",
  "timeoutAt": "2026-11-17T18:17:01.010Z",
  "proxyUsedMb": 0.035,
  "browserCostUsd": 0.002,
  "proxyCostUsd": 0.002,
  "downloads": [],
  "uploads": [],
  "costUsd": 0
}
```

`GET /v1/browser` lists your sessions, newest first, and is free.

| Query field | Type | Default | Effect |
| - | - | - | - |
| `status` | `string` | all | `active` or `destroyed`. |
| `metadata` | `string` | none | `key` matches any value, `key=value` matches one. Send it again to narrow the list. |
| `limit` | `number` | `50` | Sessions per page, 1 to 100. |
| `cursor` | `string` | none | `nextCursor` from the last page. |

```bash theme={null}
curl "https://api.stophy.dev/v1/browser?status=active&limit=5" \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

Each session in `sessions` has the fields above. `hasMore` is `true` while `nextCursor` holds a cursor for the next page. Run this before you stop work, to confirm no session is still open.

## Options

These fields go in the body of `POST /v1/browser`. Every field is optional.

| Field | Type | Effect |
| - | - | - |
| `ttl`, `activityTtl` | `number` | How long the session lives. See above. |
| `profile` | `object` | Start with the cookies and logins saved under a name, and keep what the session changes. See [Profiles](https://docs.stophy.dev/browser/profiles.md). |
| `extensionIds` | `array of string` | Up to 3 Chrome extensions you uploaded. See [Extensions](https://docs.stophy.dev/browser/extensions.md). |
| `networkPolicyId`, `allowedDomains` | `string`, `array of string` | Allow or block domains. See [Network policies](https://docs.stophy.dev/browser/network-policies.md). |
| `proxy`, `location` | `string`, `object` | Pick a country, your own proxy, or none. See [Network location](https://docs.stophy.dev/browser/network-location.md). |
| `recording` | `boolean` | Record the session as a video. Free. See [Recordings and replay](https://docs.stophy.dev/browser/recordings-and-replay.md). |
| `metadata` | `object` | Up to 10 pairs of text, keys up to 100 characters and values up to 1,000. They come back with the session, and the list can filter on them. |
| `screen` | `object` | Window size in pixels: `width` 500 to 6,144 and `height` 320 to 3,456. Sites still see a 1920x1080 display. Leave it out unless you need it. |
| `allowResizing` | `boolean` | `false` keeps the window at its size: resize commands are accepted and change nothing. |
| `pdfRenderer` | `boolean` | `true` shows PDFs in the browser's own viewer. Left out or `false`, a PDF is saved as a download. |
| `solveCaptchas` | `boolean` | Captchas the session meets are solved for you. Send `false` to leave them for you or your user to solve in the live view. |
| `captureConsole` | `boolean` | Send `true` to keep the session's console messages and page errors, to read with the `console` step of `browserRun` in [Install MCP](https://docs.stophy.dev/install-mcp#drive-a-browser). Off by default, because a few sites behave differently with it on. |
| `blockAds` | `boolean` | Ads and trackers are not loaded in the session's pages. Send `false` to load them. |
| `streamWebView` | `boolean` | The answer holds `liveViewUrl` and `interactiveLiveViewUrl` so you can watch and control the session. Send `false` to leave them out, and the answer holds only `cdpUrl`. |
| `zeroDataRetention` | `boolean` | Keep nothing from the session, so it has no replay. Not with `profile` or `recording`. See [Zero data retention](https://docs.stophy.dev/production/zero-data-retention.md). |

## Price

| What | Price |
| - | - |
| Browser time | $0.06 per hour open, $0.001 a minute |
| Browser time once a [prompt](https://docs.stophy.dev/browser/execute.md) has run | \$0.84 per hour, for the whole session |
| Traffic with the default network location | \$5 per GB |
| Traffic with no proxy, or with your own proxy | \$0.20 per GB |

Time is billed when the session closes, with one minute at least. Amounts are rounded up to \$0.002. Opening a session sets aside the most it can cost for its full `ttl`, and what it does not use comes back when it closes. Opening, listing, reading and closing cost nothing by themselves. Calls that fail cost nothing. See [Pricing](https://docs.stophy.dev/account/pricing.md).

## Limits and errors

* You can have 3 sessions open at once on the `free` tier and 10 on the `paid` tier. Another `POST /v1/browser` returns `429 rateLimited` and says how many are open. Close one to open another. See [Rate limits](https://docs.stophy.dev/production/rate-limits.md).
* A balance too low to cover the `ttl` returns `402 insufficientCredits` and no session opens.
* A call on a session that has ended returns `410 notFound` with `This browser session has ended.` Calls that need a running session, such as listing downloads, return `409 invalidRequest`.
* An id that does not exist returns `404 notFound` with `No browser session with that id.`
* `allowedDomains` and `networkPolicyId` together, `profile` with `zeroDataRetention`, and `recording` with `zeroDataRetention` each return `400 invalidRequest` that names the two fields.

## Choose another API

* [Execute](https://docs.stophy.dev/browser/execute.md) runs code or a prompt in a session you opened.
* [Tasks](https://docs.stophy.dev/browser/tasks.md) does a few steps on a public site without you opening a session.
* [Interact](https://docs.stophy.dev/scrape/interact.md) opens a session on a page you already scraped.
* [Scrape](https://docs.stophy.dev/scrape/overview) reads one page and returns it, with no session to close.
* [Batches](https://docs.stophy.dev/batches/overview) read a list of URLs in the background.


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