API ReferenceAPI v2Tasks

Create Task

Create and start a new task. You can either: 1. Start a new task without a sessionId (auto-creates a session with US proxy by default). Note: Tasks without a sessionId are one-off tasks that automatically close the session upon completion (keep_alive=false). Use sessionSettings to configure the auto-created session (e.g. proxyCountryCode, profileId, screen dimensions). 2. Start a new task in an existing session (reuse for follow-up tasks or custom configuration) Note: Without sessionSettings, a US proxy is enabled by default. Providing sessionSettings overrides defaults — proxy is only enabled if proxyCountryCode is set. For full control over session configuration (e.g. keep_alive), create a session first via POST /sessions with your desired settings, then pass that sessionId when creating tasks.

Authentication

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

Request

This endpoint expects an object.
taskstringRequired1-50000 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-10000Defaults to 100
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.
sessionSettingsobject or nullOptional

Session configuration for auto-created sessions. Only applies when session_id is not provided. Ignored when using an existing session.

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.
skillIdslist of strings or nullOptional

List of skill IDs to enable for this task. Use [’*’] to enable all available skills for the project.

Response

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

Errors