Create a browser session
Claims a warm, dedicated browser for your organization and returns it ready to drive. Load a `profile` to start signed in; set `persist_profile` to save cookies and storage back when the session closes. The session closes after `timeout_s` (at most 1,800) or on `DELETE`. Bills `vision.browser_ms` from claim to close.
POST
/v1/vision/sessions
Claims a warm, dedicated browser for your organization and returns it ready to drive. Load a `profile` to
start signed in; set `persist_profile` to save cookies and storage back when the session closes. The
session closes after `timeout_s` (at most 1,800) or on `DELETE`. Bills `vision.browser_ms` from claim to
close.
Authentication
Bearer Token (b3os_sk_ API key or b3os_pat_ token) API Key (cookie: __Host-b3os_session)
Header Parameters
Idempotency-Key
string
optional
header
A unique value (for example a UUID) that makes this request safe to retry. Scoped to your project for 24
hours: a retry with the same key, method, path and body returns the stored response with
`Idempotent-Replayed: true`, and only to the same API key. Reusing the key for a different request returns
`409 idempotency_key_conflict`.
Request Body
application/jsonprofile
string
A profile ID or name to load.
persist_profile
boolean
Save cookies and storage back to `profile` when the session closes (the profile is `locked` meanwhile).
overwrite_profile
boolean
When saving back, replace the profile even if another session saved a newer revision since this one loaded it.
viewport
object
Browser viewport in CSS pixels.
width
integer
REQUIRED
height
integer
REQUIRED
locale
string
timezone
string
user_agent
string
timeout_s
integer
Close the session this many seconds after creation.
block_ads
boolean
block_resources
string[]
Array of:
string
metadata
object
Up to 16 string key-value pairs you attach to an object for your own use. Keys are 1 to 40 characters of
`A-Z a-z 0-9 _ . : -`; values are at most 500 characters. B3OS never interprets them.
Responses
201
The session, ready to use.
application/jsonid
string
REQUIRED
object
string
REQUIRED
Enum:
browser_sessionstatus
string
REQUIRED
`active` until closed by `DELETE` (`closed`) or by its timeout (`expired`).
Enum:
active, closed, expiredcreated_at
string (date-time)
REQUIRED
expires_at
string (date-time)
REQUIRED
closed_at
string (date-time) | null
REQUIRED
timeout_s
integer
REQUIRED
viewport
object
REQUIRED
Browser viewport in CSS pixels.
width
integer
REQUIRED
height
integer
REQUIRED
profile
object | null
REQUIRED
The loaded profile, or `null`.
id
string
REQUIRED
name
string
REQUIRED
revision
integer
REQUIRED
The revision the session loaded.
persist
boolean
REQUIRED
Whether the session saves back on close.
cdp_url
string (uri)
REQUIRED
WebSocket URL of the session's CDP endpoint.
pages
object[]
Array of:
target_id
string
REQUIRED
The CDP target ID.
url
string
REQUIRED
title
string
usage
object
REQUIRED
browser_ms
integer
REQUIRED
Billed browser time so far.
timing
object
Server-side phase durations in milliseconds with microsecond resolution: the same phases as the
`Server-Timing` header, keyed `<phase>_ms`. `total_ms` is always present. Phase names are product-specific
and documented per operation. Example values in this reference are illustrative, not measurements.
total_ms
number
REQUIRED
metadata
object
REQUIRED
Up to 16 string key-value pairs you attach to an object for your own use. Keys are 1 to 40 characters of
`A-Z a-z 0-9 _ . : -`; values are at most 500 characters. B3OS never interprets them.
400
The request failed validation (`invalid_request`, `invalid_url`).
401
Missing, malformed, expired or revoked credentials (`unauthorized`).
402
The organization has no credits left, or the key reached its spend cap.
403
Authenticated but not allowed (`forbidden`, `egress_denied`).
404
No such profile in this project (`profile_not_found`).
409
The object's state does not allow this operation, or the idempotency key conflicts.
413
The request body exceeds this operation's limit.
415
The Content-Type is not accepted by this operation.
422
A parameter exceeds a plan limit (`limit_exceeded`).
429
A rate, concurrency or quota limit applies (`rate_limited`, `concurrency_limited`, `quota_exceeded`).
500
Something failed inside B3OS (`internal`). Retry with backoff.
503
The node or the product is not available right now (`node_unavailable`, `product_unavailable`, `capacity_unavailable`).
curl -X POST 'https://beta-api.b3os.org/v1/vision/sessions' \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "profile": "acme-staging", "persist_profile": true, "viewport": { "width": 1440, "height": 900 }, "timeout_s": 600}'const response = await fetch('https://beta-api.b3os.org/v1/vision/sessions', { method: 'POST', headers: { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" }, body: JSON.stringify({ "profile": "acme-staging", "persist_profile": true, "viewport": { "width": 1440, "height": 900 }, "timeout_s": 600 })});const data = await response.json();console.log(data);import requestsheaders = { 'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.post('https://beta-api.b3os.org/v1/vision/sessions', headers=headers, json={ "profile": "acme-staging", "persist_profile": true, "viewport": { "width": 1440, "height": 900 }, "timeout_s": 600})print(response.json())
201
Response
{ "id": "brs_01m5t3y30wcksxf22t9gwk9fwb", "object": "browser_session", "status": "active", "created_at": "2026-10-25T18:30:00.002Z", "expires_at": "2026-10-25T18:40:00.002Z", "closed_at": null, "timeout_s": 600, "viewport": { "width": 1440, "height": 900 }, "profile": { "id": "prof_01m5t3v4507bhcb5jqrgzfvfsk", "name": "acme-staging", "revision": 4, "persist": true }, "cdp_url": "wss://beta-api.b3os.org/v1/vision/sessions/brs_01m5t3y30wcksxf22t9gwk9fwb/cdp", "usage": { "browser_ms": 0 }, "timing": { "claim_ms": 2.1, "profile_ms": 6.4, "total_ms": 8.9 }, "metadata": {}}API Playground
Try this endpoint
POST
/v1/vision/sessions