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.

POST /tasks

Create Task

JavaScript

const options = {
  method: 'POST',
  headers: {'X-Browser-Use-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    task: '<string>',
    llm: 'browser-use-2.0',
    startUrl: '<string>',
    maxSteps: 100,
    structuredOutput: '<string>',
    sessionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    metadata: {},
    secrets: {},
    allowedDomains: ['<string>'],
    opVaultId: '<string>',
    sessionSettings: {
      profileId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
      proxyCountryCode: 'us',
      browserScreenWidth: 3232,
      browserScreenHeight: 1888,
      enableRecording: false
    },
    highlightElements: false,
    flashMode: false,
    thinking: false,
    vision: true,
    systemPromptExtension: '',
    judge: false,
    judgeGroundTruth: '<string>',
    skillIds: ['<string>']
  })
};

fetch('https://api.browser-use.com/api/v2/tasks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://api.browser-use.com/api/v2/tasks \
  --header 'Content-Type: application/json' \
  --header 'X-Browser-Use-API-Key: <api-key>' \
  --data '
{
  "task": "<string>",
  "llm": "browser-use-2.0",
  "startUrl": "<string>",
  "maxSteps": 100,
  "structuredOutput": "<string>",
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "metadata": {},
  "secrets": {},
  "allowedDomains": [
    "<string>"
  ],
  "opVaultId": "<string>",
  "sessionSettings": {
    "profileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "proxyCountryCode": "us",
    "browserScreenWidth": 3232,
    "browserScreenHeight": 1888,
    "enableRecording": false
  },
  "highlightElements": false,
  "flashMode": false,
  "thinking": false,
  "vision": true,
  "systemPromptExtension": "",
  "judge": false,
  "judgeGroundTruth": "<string>",
  "skillIds": [
    "<string>"
  ]
}
'

import requests

url = "https://api.browser-use.com/api/v2/tasks"

payload = {
    "task": "<string>",
    "llm": "browser-use-2.0",
    "startUrl": "<string>",
    "maxSteps": 100,
    "structuredOutput": "<string>",
    "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "metadata": {},
    "secrets": {},
    "allowedDomains": ["<string>"],
    "opVaultId": "<string>",
    "sessionSettings": {
        "profileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "proxyCountryCode": "us",
        "browserScreenWidth": 3232,
        "browserScreenHeight": 1888,
        "enableRecording": False
    },
    "highlightElements": False,
    "flashMode": False,
    "thinking": False,
    "vision": True,
    "systemPromptExtension": "",
    "judge": False,
    "judgeGroundTruth": "<string>",
    "skillIds": ["<string>"]
}
headers = {
    "X-Browser-Use-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

202

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

{
  "detail": "Browser session is stopped. Please start a new session and try again."
}

{
  "detail": "Session not found"
}

{
  "loc": [
    "<string>"
  ],
  "msg": "<string>",
  "type": "<string>"
}

{
  "detail": "Too many concurrent active sessions. Please wait for one to finish, kill one, or upgrade your plan."
}

Authorizations

X-Browser-Use-API-Key · string · header · required

Body

application/json

Request model for creating a task

task · string · required

The task prompt/instruction for the agent.

Required string length: 1 - 50000

llm · enum<string> · default: browser-use-2.0

The LLM model to use for the agent.

Available options: browser-use-llm, browser-use-2.0, gpt-4.1, gpt-4.1-mini, o4-mini, o3, gemini-2.5-flash, gemini-2.5-pro, gemini-3-pro-preview, gemini-3-flash-preview, gemini-flash-latest, gemini-flash-lite-latest, claude-sonnet-4-20250514, claude-sonnet-4-5-20250929, claude-sonnet-4-6, claude-opus-4-5-20251101, gpt-4o, gpt-4o-mini, llama-4-maverick-17b-128e-instruct, claude-3-7-sonnet-20250219

startUrl · string | null

The URL to start the task from.

maxSteps · integer · default: 100

Maximum number of steps the agent can take before stopping.

Required range: 1 <= x <= 10000

structuredOutput · string | null

The stringified JSON schema for the structured output.

sessionId · string<uuid> | null

The ID of the session where the task will run.

metadata · Metadata · object | null

The metadata for the task. Up to 10 key-value pairs.

Show child attributes

secrets · Secrets · object | null

The secrets for the task. Allowed domains are not required for secrets to be injected, but are recommended.

Show child attributes

allowedDomains · string[] | null

The allowed domains for the task.

opVaultId · string | null

The ID of the 1Password vault to use for the task. This is used to inject secrets into the task.

sessionSettings · SessionSettings · object | null

Session configuration for auto-created sessions. These settings only apply when no session_id is provided.

Show child attributes

highlightElements · boolean · default: false

Tells the agent to highlight interactive elements on the page.

flashMode · boolean · default: false

Whether agent flash mode is enabled.

thinking · boolean · default: false

Whether agent thinking mode is enabled.

vision · boolean string · default: true

Whether agent vision capabilities are enabled. Set to 'auto' to let the agent decide based on the model capabilities.

systemPromptExtension · string · default: ""

Optional extension to the agent system prompt.

Maximum string length: 2000

judge · boolean · default: false

Enable judge mode to evaluate task completion against ground truth.

judgeGroundTruth · string | null

Expected answer for judge evaluation.

Maximum string length: 10000

judgeLlm · enum<string> | null

The LLM model to use for judging. If not provided, uses the default judge LLM.

Available options: browser-use-llm, browser-use-2.0, gpt-4.1, gpt-4.1-mini, o4-mini, o3, gemini-2.5-flash, gemini-2.5-pro, gemini-3-pro-preview, gemini-3-flash-preview, gemini-flash-latest, gemini-flash-lite-latest, claude-sonnet-4-20250514, claude-sonnet-4-5-20250929, claude-sonnet-4-6, claude-opus-4-5-20251101, gpt-4o, gpt-4o-mini, llama-4-maverick-17b-128e-instruct, claude-3-7-sonnet-20250219

skillIds · string[] | null

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

Response

202

application/json

Successful Response

Response model for creating a task

id · string<uuid> · required

Unique identifier for the created task

sessionId · string<uuid> · required

Session ID where the task was created