---
title: "Prepare an isolated browser for a session [write]"
method: POST
path: "/sessions/{id}/browser"
---

# Prepare an isolated browser for a session \[write\]

`POST /sessions/{id}/browser`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/sessions/{id}/browser`
- Auth: HTTP bearer

Prepare before sending the task's first turn. Requires an active session, positive credit balance and remaining session budget. An identical repeated request reuses the browser; a different configuration or an ended browser returns 409. The browser has a 15-minute lifetime, fixed viewport and bounded actions. Structured Google Flights verification checks visible route, dates, passengers, cabin and results; tasks without verification remain unverified. Browser usage is billed separately from model and runtime usage.

## Path parameters

- `id` string, required

## Request body

- BrowserTask
  - `task` string, required
  - `startUrl` string, uri, required
  - `viewport` object, required
    - `width` integer, required
    - `height` integer, required
  - `verification` object
    - `kind` 'google-flights', required
    - `origin` string, required
    - `destination` string, required
    - `departureDate` string, required
    - `returnDate` string
    - `passengers` integer, required
    - `cabin` 'economy' | 'premium-economy' | 'business' | 'first', required

## Response `201`

Authorized browser state, or null when the session has no browser. Provider credentials, interactive viewer links and browser connection URLs are never returned.

- object
  - `browser` SessionBrowser, required
    - `id` string, required
    - `status` 'preparing' | 'running' | 'completed' | 'blocked' | 'failed' | 'stopped', required
    - `viewerUrl` unknown, required
    - `url` string, required
    - `startedAt` string, date-time, required
    - `expiresAt` string, date-time, required
    - `endedAt` string, date-time, nullable, required
    - `elapsedMs` number, required
    - `actionCount` integer, required
    - `progress` string
    - `claim` string: The agent's completion claim, separate from task verification.
    - `resolvedModel` string: Resolved Jev model reported by OpenRouter.
    - `error` string
    - `actions` object[], required
      - `id` string, required
      - `verb` string, required
      - `detail` string, required
      - `timestamp` string, date-time, required
      - `status` string, required
    - `verification` object, required
      - `status` 'passed' | 'failed' | 'unverified', required
      - `checks` object[], required
        - `label` string, required
        - `status` 'passed' | 'failed' | 'unverified', required
        - `detail` string, required
    - `lastScreenshot` string, nullable, required: Latest observed or final JPEG as a data URL when capture succeeded.
    - `lastScreenshotAt` string, date-time, nullable: Time the latest screenshot was captured successfully.
    - `cleanupPending` boolean, required: A terminal browser may still be releasing provider resources; cleanup is retried durably.
    - `costs` object, required: Recorded billed USD, including the fixed Mercury text-entry helper. Receipts can arrive after completion.
      - `decisionUsd` number, required
      - `helperUsd` number, required
      - `browserUsd` number, required
      - `runtimeUsd` number, required
      - `totalUsd` number, required: Metered cost including waived usage.
      - `chargedUsd` number, required: Actual amount charged after billing waivers.

## Other responses

- `400`: Error — { error: { code, message } }
- `402`: Error — { error: { code, message } }
- `409`: Error — { error: { code, message } }
- `502`: Error — { error: { code, message } }
- `503`: Error — { error: { code, message } }
- `default`: Error — { error: { code, message } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 6 info
  - added the media type `application/json` for the response with the status `400`
  - added the media type `application/json` for the response with the status `402`
  - added the media type `application/json` for the response with the status `409`
  - added the media type `application/json` for the response with the status `502`
  - …2 more

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/sessions/:id/browser/post.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/8280a065ef6a?raw)