---
title: "Create a browser session"
method: POST
path: "/v1/browser/session"
---

# Create a browser session

`POST /v1/browser/session`

## Request

- Base URL: `https://api.roveapi.com`
- URL: `https://api.roveapi.com/v1/browser/session`
- Auth: HTTP bearer

## Request body

- object
  - `supervised` boolean: Opt in to exclusive human takeover, explicit handback, and fresh-observation fencing.
  - `viewport_mode` 'follow-human' | 'fixed': Supervised sessions only. Whether human stage changes resize the remote page (`follow-human`) or leave its agent viewport fixed (`fixed`).
  - `viewport` object
    - `width` integer, required
    - `height` integer, required
  - `record_video` boolean, required
  - `user_agent` string
  - `locale` string, required
  - `timezone` string
  - `block_resources` string[]

## Response `201`

Successful response

- object
  - `session_id` string, required
  - `connection_token` string, required
  - `expires_at` string, required
  - `environment` 'live' | 'test', required
  - `supervised` boolean, required
  - `viewport_mode` 'follow-human' | 'fixed'
  - `restore` object, nullable: Supervised sessions only. Answer it with the restore_pages action (decision restore or dismiss).
    - `available` true, required
    - `page_count` integer, required
    - `ended_reason` string, required: Why the previous session ended: worker_lost, page_memory_exhausted, browser_unresponsive, runtime_restarted, or unknown.
    - `ended_at` string, required
    - `pages` object[], required
      - `url` string, required
      - `title` string, required

## Other responses

- `401`: RFC 7807 authentication problem
- `402`: RFC 7807 insufficient-credits: the balance does not cover this operation; carries the balance, the packs this key may buy and next_step (buy_credits or ask_owner)
- `409`: RFC 7807 profile-busy: another active supervised session on this key uses the browser profile; session_id names it
- `410`: RFC 7807 expired or replayed admission problem
- `429`: RFC 7807 supervised-session-limit: the account runs its most supervised sessions; honour Retry-After
- `503`: RFC 7807 pool-exhausted or worker-unavailable (both with Retry-After), or browser-crash

---

[API](https://skmtc.dev/roveapi/apis/rove-api.md) · [All operations](https://skmtc.dev/roveapi/apis/rove-api/llms.txt) · [OpenAPI document](https://skmtc.dev/roveapi/apis/rove-api/revisions/0e5d69bde586?raw)