Create Session

Create a session and/or dispatch a task.

• Without session_id, without task: creates a new idle session (e.g. for file uploads).
• Without session_id, with task: creates a new session and dispatches the task.
• With session_id, with task: dispatches the task to an existing idle session.
• With session_id, without task: 422 — task is required when targeting an existing session.

If keep_alive is false (default), the session auto-stops when the task finishes. If keep_alive is true, the session stays idle after the task, ready for follow-ups.

POST /sessions

Create Session

JavaScript

const options = {
  method: 'POST',
  headers: {'X-Browser-Use-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    task: '<string>',
    model: 'claude-sonnet-4.6',
    sessionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    keepAlive: false,
    maxCostUsd: 123,
    profileId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    workspaceId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    proxyCountryCode: 'us',
    outputSchema: {},
    enableScheduledTasks: false,
    enableRecording: false,
    skills: true,
    agentmail: true,
    cacheScript: true
  })
};

fetch('https://api.browser-use.com/api/v3/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

200

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "created",
  "model": "bu-mini",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "title": "<string>",
  "output": "<unknown>",
  "outputSchema": {},
  "stepCount": 0,
  "lastStepSummary": "<string>",
  "isTaskSuccessful": true,
  "liveUrl": "<string>",
  "recordingUrls": [],
  "profileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "proxyCountryCode": "ad",
  "maxCostUsd": "<string>",
  "totalInputTokens": 0,
  "totalOutputTokens": 0,
  "proxyUsedMb": "0",
  "llmCostUsd": "0",
  "proxyCostUsd": "0",
  "browserCostUsd": "0",
  "totalCostUsd": "0",
  "screenshotUrl": "<string>",
  "agentmailEmail": "<string>"
}

Authorizations

X-Browser-Use-API-Key · string · header · required

Body

application/json

Create a new session, dispatch a task, or both.

• No sessionId + no task: creates an idle session (useful for uploading files before running a task).
• No sessionId + task: creates a new session and immediately runs the task.
• sessionId + task: dispatches the task to an existing idle session.
• sessionId + no task: returns 422 — a task is required when targeting an existing session.

task · string | null

The natural-language instruction for the agent to execute (e.g. "Go to amazon.com and find the best-rated wireless mouse under $50"). Required when dispatching to an existing session.

model · enum<string> · default: claude-sonnet-4.6

The model to use. "gemini-3-flash" is fast and cheap, "claude-sonnet-4.6" is balanced, "claude-opus-4.6" is most capable. See BuModel for details.

Available options: bu-mini, bu-max, bu-ultra, gemini-3-flash, claude-sonnet-4.6, claude-opus-4.6

sessionId · string<uuid> | null

ID of an existing idle session to dispatch the task to. If omitted, a new session is created.

keepAlive · boolean · default: false

If true, the session stays alive in idle state after the task completes instead of automatically stopping. This lets you dispatch follow-up tasks to the same session, preserving browser state and files.

maxCostUsd · number string

Maximum total cost in USD allowed for this session. The task will be stopped if this limit is reached. If omitted, a default limit applies (capped by your available balance).

profileId · string<uuid> | null

ID of a browser profile to load into the session. Profiles persist cookies, local storage, and other browser state across sessions. Create profiles via the Profiles API.

workspaceId · string<uuid> | null

ID of a workspace to attach to the session. Workspaces provide persistent file storage that carries across sessions. Create workspaces via the Workspaces API.

proxyCountryCode · enum<string> | null · default: us

Country code for the browser proxy (e.g. "US", "DE", "JP"). Set to null to disable the proxy. The proxy routes browser traffic through the specified country, useful for accessing geo-restricted content.

Available options: ad, ae, af, ag, ai, al, am, an, ao, aq, ar, as, at, au, aw, az, ba, bb, bd, be, bf, bg, bh, bi, bj, bl, bm, bn, bo, bq, br, bs, bt, bv, bw, by, bz, ca, cc, cd, cf, cg, ch, ck, cl, cm, co, cr, cs, cu, cv, cw, cx, cy, cz, de, dj, dk, dm, do, dz, ec, ee, eg, eh, er, es, et, fi, fj, fk, fm, fo, fr, ga, gd, ge, gf, gg, gh, gi, gl, gm, gn, gp, gq, gr, gs, gt, gu, gw, gy, hk, hm, hn, hr, ht, hu, id, ie, il, im, in, iq, ir, is, it, je, jm, jo, jp, ke, kg, kh, ki, km, kn, kp, kr, kw, ky, kz, la, lb, lc, li, lk, lr, ls, lt, lu, lv, ly, ma, mc, md, me, mf, mg, mh, mk, ml, mm, mn, mo, mp, mq, mr, ms, mt, mu, mv, mw, mx, my, mz, na, nc, ne, nf, ng, ni, nl, no, np, nr, nu, nz, om, pa, pe, pf, pg, ph, pk, pl, pm, pn, pr, ps, pt, pw, py, qa, re, ro, rs, ru, rw, sa, sb, sc, sd, se, sg, sh, si, sj, sk, sl, sm, sn, so, sr, ss, st, sv, sx, sy, sz, tc, td, tf, tg, th, tj, tk, tl, tm, tn, to, tr, tt, tv, tw, tz, ua, ug, uk, us, uy, uz, va, vc, ve, vg, vi, vn, vu, wf, ws, xk, ye, yt, za, zm, zw

outputSchema · Outputschema · object

A JSON Schema that the agent's final output must conform to. When set, the agent will return structured data matching this schema in the output field of the response. Example: {"type": "object", "properties": {"price": {"type": "number"}, "title": {"type": "string"}}}.

enableScheduledTasks · boolean · default: false

If true, the agent can create scheduled tasks that run on a recurring basis (e.g. "every Monday morning, check my inbox and summarize new emails"). Scheduled tasks are tied to your project and persist beyond the session. Note: all scheduled tasks are visible project-wide, so avoid enabling this in multi-user setups where task isolation is needed.

enableRecording · boolean · default: false

If true, records a video of the browser session. The recording URLs will be available in the recordingUrls field of the session response after the task completes.

skills · boolean · default: true

If true, enables built-in agent skills like Google Sheets integration and file management. Set to false to restrict the agent to browser-only actions.

agentmail · boolean · default: true

If true, provisions a temporary email inbox (via AgentMail) for the session. The email address is available in the agentmailEmail field of the session response. Useful for tasks that require email verification or sign-ups.

cacheScript · boolean | null

Controls deterministic script caching. null (default): auto-detected — enabled when the task contains {{value}} brackets and a workspace is attached. true: force-enable script caching even without brackets (caches the exact task). false: force-disable, even if brackets are present. When active, the first call runs the full agent and saves a reusable script. Subsequent calls with the same task template execute the cached script with $0 LLM cost. Requires workspace_id when enabled. Example: "Get prices from {{https://example.com}} for {{electronics}}".

Response

200

application/json

Successful Response

Represents a session and its current state.

Poll this endpoint to track task progress. The status field indicates the session lifecycle stage, and output contains the agent's structured result once the task completes.

id · string<uuid> · required

Unique session identifier.

status · enum<string> · required

Current session lifecycle status. Progresses through: created (sandbox starting) → idle (ready, waiting for task) → running (task executing) → stopped / timed_out / error. Poll this field to track progress.

Available options: created, idle, running, stopped, timed_out, error

model · enum<string> · required

The model tier used for this session.

Available options: bu-mini, bu-max, bu-ultra, gemini-3-flash, claude-sonnet-4.6, claude-opus-4.6

createdAt · string<date-time> · required

When the session was created.

updatedAt · string<date-time> · required

When the session was last updated.

title · string | null

Auto-generated short title summarizing the task. Available after the task starts running.

output · any | null

The agent's final output. If outputSchema was provided, this will be structured data conforming to that schema. Otherwise it may be a free-form string or null. Populated once the task completes, regardless of whether isTaskSuccessful is true or false.

outputSchema · Outputschema · object

The JSON Schema that was requested for structured output, if any.

stepCount · integer · default: 0

Number of steps the agent has executed so far.

lastStepSummary · string | null

Human-readable summary of the most recent agent step (e.g. "Clicking the Submit button"). Useful for showing real-time progress.

isTaskSuccessful · boolean | null

Whether the task completed successfully. true if the agent achieved the goal, false if it failed or gave up, null if the task is still running or no task was dispatched.

liveUrl · string | null

URL to view the live browser session. Available immediately on session creation — can be embedded in an iframe to show the browser in real time.

recordingUrls · string[]

URLs to download session recordings. Only populated if enableRecording was set to true and the task has completed.

profileId · string<uuid> | null

ID of the browser profile loaded in this session, if any.

workspaceId · string<uuid> | null

ID of the workspace attached to this session, if any.

proxyCountryCode · enum<string> | null

Country code of the proxy used for this session, or null if no proxy.

Available options: ad, ae, af, ag, ai, al, am, an, ao, aq, ar, as, at, au, aw, az, ba, bb, bd, be, bf, bg, bh, bi, bj, bl, bm, bn, bo, bq, br, bs, bt, bv, bw, by, bz, ca, cc, cd, cf, cg, ch, ck, cl, cm, co, cr, cs, cu, cv, cw, cx, cy, cz, de, dj, dk, dm, do, dz, ec, ee, eg, eh, er, es, et, fi, fj, fk, fm, fo, fr, ga, gd, ge, gf, gg, gh, gi, gl, gm, gn, gp, gq, gr, gs, gt, gu, gw, gy, hk, hm, hn, hr, ht, hu, id, ie, il, im, in, iq, ir, is, it, je, jm, jo, jp, ke, kg, kh, ki, km, kn, kp, kr, kw, ky, kz, la, lb, lc, li, lk, lr, ls, lt, lu, lv, ly, ma, mc, md, me, mf, mg, mh, mk, ml, mm, mn, mo, mp, mq, mr, ms, mt, mu, mv, mw, mx, my, mz, na, nc, ne, nf, ng, ni, nl, no, np, nr, nu, nz, om, pa, pe, pf, pg, ph, pk, pl, pm, pn, pr, ps, pt, pw, py, qa, re, ro, rs, ru, rw, sa, sb, sc, sd, se, sg, sh, si, sj, sk, sl, sm, sn, so, sr, ss, st, sv, sx, sy, sz, tc, td, tf, tg, th, tj, tk, tl, tm, tn, to, tr, tt, tv, tw, tz, ua, ug, uk, us, uy, uz, va, vc, ve, vg, vi, vn, vu, wf, ws, xk, ye, yt, za, zm, zw

maxCostUsd · string | null

Maximum cost limit in USD set for this session.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

totalInputTokens · integer · default: 0

Total LLM input tokens consumed by this session.

totalOutputTokens · integer · default: 0

Total LLM output tokens consumed by this session.

proxyUsedMb · string · default: 0

Proxy bandwidth used in megabytes.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

llmCostUsd · string · default: 0

Cost of LLM usage in USD.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

proxyCostUsd · string · default: 0

Cost of proxy bandwidth in USD.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

browserCostUsd · string · default: 0

Cost of browser compute time in USD.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

totalCostUsd · string · default: 0

Total session cost in USD (LLM + proxy + browser).

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

screenshotUrl · string | null

URL of the latest browser screenshot. This is a presigned URL that expires after 5 minutes. A new URL is generated each time you fetch the session.

agentmailEmail · string | null

Temporary email address provisioned for this session (via AgentMail). Only present if agentmail was enabled.