API ReferenceLatest API (v2)Tasks

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) 2. Start a new task in an existing session (reuse for follow-up tasks or custom configuration) Important: Proxy configuration (proxyCountryCode) is a session-level setting, not a task-level setting. To use a custom proxy location, create a session first via POST /sessions with your desired proxyCountryCode, 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 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.
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