API Referencev2 API (Current)Tasks

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)

Authentication

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

Request

This endpoint expects an object.
taskstringRequired1-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.
maxStepsintegerOptional1-300Defaults 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. Up to 10 key-value pairs.

secretsmap from strings to strings or nullOptional
The secrets for the task. Allowed domains are not required for secrets to be injected, but are recommended.
allowedDomainslist of strings or nullOptional
The allowed domains for the task.
opVaultIdstring or nullOptional
The ID of the 1Password vault to use for the task. This is used to inject secrets into 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.
visionboolean or "auto"Optional
Whether agent vision capabilities are enabled. Set to 'auto' to let the agent decide based on the model capabilities.
systemPromptExtensionstringOptional<=2000 charactersDefaults to
Optional extension to the agent system prompt.
judgebooleanOptionalDefaults to false
Enable judge mode to evaluate task completion against ground truth.
judgeGroundTruthstring or nullOptional<=10000 characters
Expected answer for judge evaluation.
judgeLlmenum or nullOptional
The LLM model to use for judging. If not provided, uses the default judge LLM.

Response

Successful Response
idstringformat: "uuid"
Unique identifier for the created task
sessionIdstringformat: "uuid"
Session ID where the task was created

Errors