Create Task

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: 'ad',
      browserScreenWidth: 3232,
      browserScreenHeight: 1888
    },
    highlightElements: false,
    flashMode: false,
    thinking: false,
    vision: true,
    systemPromptExtension: '',
    judge: false,
    judgeGroundTruth: '<string>',
    judgeLlm: 'browser-use-llm',
    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));

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

Tasks

Create Task

Create and start a new task.

You can either:

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).
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

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: 'ad',
      browserScreenWidth: 3232,
      browserScreenHeight: 1888
    },
    highlightElements: false,
    flashMode: false,
    thinking: false,
    vision: true,
    systemPromptExtension: '',
    judge: false,
    judgeGroundTruth: '<string>',
    judgeLlm: 'browser-use-llm',
    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));

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

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-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

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

Show child attributes

secrets

Secrets · object

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

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

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-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

Successful Response

Response model for creating a task

string<uuid>

required

Unique identifier for the created task

sessionId

string<uuid>

required

Session ID where the task was created

List Tasks

Get Task

⌘I

API v2 (Stable)

BU Agent API (Experimental)

Create Task

Authorizations

Body

Response