API ReferenceTasks

Create Task

You can either:

  1. Start a new task (auto creates a new simple session)
  2. Start a new task in an existing session (you can create a custom session before starting the task and reuse it for follow-up tasks)

Headers

X-Browser-Use-API-KeystringRequired

Request

This endpoint expects an object.
taskstringRequired>=1 character<=20000 characters

The task prompt/instruction for the agent.

llmenumOptional
The LLM model to use for the agent.
startUrlstring or nullOptional
The URL to start the task from.
maxStepsintegerOptional>=1<=200Defaults to 30
Maximum number of steps the agent can take before stopping.
structuredOutputstring or nullOptional
The stringified JSON schema for the structured output.
sessionIdstring or nullOptionalformat: "uuid"
The ID of the session where the task will run.
metadatamap from strings to strings or nullOptional
The metadata for the task.
secretsmap from strings to strings or nullOptional
The secrets for the task.
allowedDomainslist of strings or nullOptional
The allowed domains for the task.
highlightElementsbooleanOptionalDefaults to false
Tells the agent to highlight interactive elements on the page.
flashModebooleanOptionalDefaults to false
Whether agent flash mode is enabled.
thinkingbooleanOptionalDefaults to false
Whether agent thinking mode is enabled.
visionbooleanOptionalDefaults to true
Whether agent vision capabilities are enabled.
systemPromptExtensionstringOptional<=2000 charactersDefaults to
Optional extension to the agent system prompt.

Response

Successful Response
idstringformat: "uuid"
Unique identifier for the created task

Errors