> ## 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 or run code in it, record it, then close it. Covers lifetime, options, recordings, replay and errors.

A browser session is a cloud browser that keeps its pages, tabs and login across your calls. For one page read without clicks, use [Scrape](https://docs.stophy.dev/scrape/overview).

```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()) as { id: string; cdpUrl: string };
console.log(session.id, session.cdpUrl);
```

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

import httpx

response = httpx.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"])
```

The session closes after `activityTtl` seconds with no call (default 300, from 10) or `ttl` seconds after it opens (default 600, from 30), whichever comes first. Both go up to 21,600. It bills for the time it is open, so close it when you finish.

```json theme={null}
{
  "id": "f39685c4-c706-4b7d-b08d-86e33b8c66fd",
  "timeoutAt": "2026-11-20T20:52:21.160Z",
  "expiresAt": "2026-11-20T20:56:21.157Z",
  "cdpUrl": "wss://api.stophy.dev/v1/interact/f39685c4-…/cdp?…",
  "liveViewUrl": "https://live.stophy.dev/f39685c4-…"
}
```

Keep `id`: every other call on the session uses it. `cdpUrl` carries a token, so keep it private. `liveViewUrl` lets you watch the session and `interactiveLiveViewUrl` lets you control it. `timeoutAt` moves forward with each call, and `expiresAt` is `ttl` after opening.

To recover a session after a dropped answer, send the same `Idempotency-Key` header, key and body within 24 hours. A different body or an ended session returns `409`. On `503` with `Retry-After`, retry with the same key.

## Drive it

* Over CDP: `chromium.connectOverCDP(cdpUrl)` in Playwright, or `puppeteer.connect({ browserWSEndpoint: cdpUrl })`. Use the page that is already open. CDP activity counts as a call for `activityTtl`, and disconnecting does not close the session.
* Over HTTP: [run code or a prompt](https://docs.stophy.dev/browser/execute.md) in it.

## Close, read and list

`DELETE /v1/browser/{session_id}` closes the session and bills it. The answer has `costUsd`, `sessionDurationMs`, `proxyBytes` split by network in `exitBytes` (see [Network](https://docs.stophy.dev/browser/network-location.md)) and `recordingStatus`. Closing it again charges nothing and returns the bill as `sessionCostUsd`.

`GET /v1/browser/{session_id}` is free. A running session lists its `downloads` and `uploads`. A closed one has `status: "destroyed"`, `finishedAt`, and `browserCostUsd`, `proxyCostUsd` and `proxyUsedMb` to tell time from traffic.

`GET /v1/browser` is free and lists sessions, newest first. Run `?status=active` before you stop work to confirm none is open. Filter with `status` (`active` or `destroyed`) and `metadata` (`key` or `key=value`, repeat to narrow). Page with `limit` (50, up to 100) and `cursor`, set to `nextCursor` while `hasMore` is `true`.

## Options

Every field of `POST /v1/browser` is optional.

| Field | What it does |
| - | - |
| `profile` | Cookies and logins saved under a name. See [Profiles](https://docs.stophy.dev/browser/profiles.md). |
| `extensionIds` | Up to 3 uploaded extensions. See [Profiles and extensions](https://docs.stophy.dev/browser/profiles.md#extensions). |
| `networkPolicyId`, `allowedDomains` | Allow or block domains. See [Network](https://docs.stophy.dev/browser/network-location.md#network-policies). |
| `proxy`, `location` | Country, your own proxy, or none. See [Network](https://docs.stophy.dev/browser/network-location.md). |
| `recording` | `true` records every tab as an MP4. See [Recordings and replay](#recordings-and-replay). |
| `metadata` | Up to 10 text pairs, keys up to 100 characters, values up to 1,000. They come back with the session and filter the list. |
| `screen` | Window `width` 500 to 6,144 and `height` 320 to 3,456 pixels, default 1920x1080. Sites read it as the display. |
| `allowResizing` | `false` keeps the window size: resize commands are accepted and change nothing. |
| `pdfRenderer` | `true` shows PDFs in the browser viewer. Otherwise a PDF is saved as a download. |
| `solveCaptchas` | Captchas are solved for you. `false` leaves them for you or your user in the live view. |
| `captureConsole` | `true` keeps console messages and page errors for the `console` step of `stophy_browser_run` in [MCP server](https://docs.stophy.dev/install-mcp.md#drive-a-browser). Off by default: a few sites behave differently with it on. |
| `blockAds` | `false` loads ads and trackers. |
| `streamWebView` | `false` leaves out the live view links. |
| `zeroDataRetention` | Keep nothing, so no replay. Not with `profile` or `recording`. See [Zero data retention](https://docs.stophy.dev/production/zero-data-retention.md). |

## Recordings and replay

Both are free. A recording is a video of every tab. A replay lists the pages the session visited and the steps run on each, kept 24 hours after the session closes, and needs no `recording`.

Open the session with `"recording": true`. `recordingStatus` is `recording` while the session runs and `processing` while the video is made after it closes, then `ready` or `failed` (never made). `none` means not recorded, or deleted.

* `GET /v1/browser/{session_id}/recording` returns the status and, when `ready`, `recordingUrl`: an MP4 that needs no key for 15 minutes. Read it again for a new link. The video is kept 7 days. `recordingTruncated: true` means it ends early.
* `DELETE /v1/browser/{session_id}/recording` removes the video at once. The replay stays.
* `GET /v1/browser/{session_id}/replay` returns `pages`, each with `pageId`, `url`, `title`, `at` (milliseconds since 1970) and `steps` (the calls your code made). `GET /v1/browser/{session_id}/replay/{page_id}` adds `screenshot`, a Base64 JPEG. `maxTextLength` cuts text values.

## Errors

| Code | Cause | Fix |
| - | - | - |
| `400 invalidRequest` | `allowedDomains` with `networkPolicyId`, or `profile` or `recording` with `zeroDataRetention` | Send one of the two named fields. |
| `402 insufficientCredits` | The balance cannot cover `ttl`. No session opens. | Add funds or lower `ttl`. |
| `404 notFound` | An unknown session or replay page, or no video to delete | Check the ID. |
| `409 invalidRequest` | A call that needs a running session, or deleting a video still being made | Open a new session, or wait for `ready` or `failed`. |
| `410 notFound` | `This browser session has ended.` | Open a new session. |
| `429 rateLimited` | Over the open-session limit. The message says how many are open. | Close one. See [Rate limits](https://docs.stophy.dev/production/rate-limits.md). |

Other codes are on [Errors](https://docs.stophy.dev/api-reference/errors.md).

## Next

* [Execute](https://docs.stophy.dev/browser/execute.md): run code or a prompt in the session.
* [Tasks](https://docs.stophy.dev/browser/tasks.md): do a few steps on a public site with no session of yours.
* [Interact](https://docs.stophy.dev/scrape/interact.md): open a session on a page you scraped.


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