API ReferenceAPI v3 (Experimental)Sessions

Create Session

Run a task in a session. - Without session_id: creates a new session, starts a sandbox, and dispatches the task. - With session_id: dispatches the task to an existing idle 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.

Authentication

X-Browser-Use-API-Keystring
API Key authentication via header

Request

This endpoint expects an object.
taskstringRequired
modelenumOptional
Allowed values:
sessionIdstring or nullOptionalformat: "uuid"
keepAlivebooleanOptionalDefaults to false
maxCostUsddouble or string or nullOptional
profileIdstring or nullOptionalformat: "uuid"
proxyCountryCodeenum or nullOptional
outputSchemamap from strings to any or nullOptional

Response

Successful Response
idstringformat: "uuid"
statusenum
modelenum
Allowed values:
createdAtdatetime
updatedAtdatetime
titlestring or null
liveUrlstring or null
profileIdstring or nullformat: "uuid"
proxyCountryCodeenum or null
maxCostUsdstring or nullformat: "^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$"
totalInputTokensinteger or nullDefaults to 0
totalOutputTokensinteger or nullDefaults to 0
proxyUsedMbstring or nullformat: "^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$"Defaults to 0
llmCostUsdstring or nullformat: "^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$"Defaults to 0
proxyCostUsdstring or nullformat: "^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$"Defaults to 0
totalCostUsdstring or nullformat: "^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$"Defaults to 0

Errors