Skip to main content
GET
/
sessions
/
{session_id}
Get Session
const options = {method: 'GET', headers: {'X-Browser-Use-API-Key': '<api-key>'}};

fetch('https://api.browser-use.com/api/v3/sessions/{session_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "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

Path Parameters

​
session_id
string<uuid>
required

Response

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.