Create Run

const options = {
  method: 'POST',
  headers: {'X-Browser-Use-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    task: '<string>',
    outputSchema: {},
    model: 'gpt-6-luna',
    modelParams: {},
    sessionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    workspaceId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    browserSettings: {
      profileId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
      proxyCountryCode: 'us',
      customProxy: {
        host: '<string>',
        port: 32768,
        username: '<string>',
        password: '<string>',
        ignoreCertErrors: false
      },
      screenWidth: 3232,
      screenHeight: 1888,
      allowResizing: true,
      record: true,
      extensionIds: ['3c90c3cc-0d44-4b50-8888-8dd25736052a']
    },
    agentmail: false,
    agentcardWalletId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    stripeLinkConnectionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    attachedFileIds: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    secretBindings: [
      {
        alias: '<string>',
        source: {type: 'inline', value: '<string>'},
        allowedDomains: ['<string>']
      }
    ],
    opVaultId: '<string>',
    opVaultAllowedDomains: ['<string>'],
    judge: {context: '<string>'},
    maxCostUsd: 1
  })
};

fetch('https://api.browser-use.com/api/v4/runs', 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/v4/runs \
  --header 'Content-Type: application/json' \
  --header 'X-Browser-Use-API-Key: <api-key>' \
  --data '
{
  "task": "<string>",
  "outputSchema": {},
  "model": "gpt-6-luna",
  "modelParams": {},
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "browserSettings": {
    "profileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "proxyCountryCode": "us",
    "customProxy": {
      "host": "<string>",
      "port": 32768,
      "username": "<string>",
      "password": "<string>",
      "ignoreCertErrors": false
    },
    "screenWidth": 3232,
    "screenHeight": 1888,
    "allowResizing": true,
    "record": true,
    "extensionIds": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ]
  },
  "agentmail": false,
  "agentcardWalletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "stripeLinkConnectionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "attachedFileIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "secretBindings": [
    {
      "alias": "<string>",
      "source": {
        "type": "inline",
        "value": "<string>"
      },
      "allowedDomains": [
        "<string>"
      ]
    }
  ],
  "opVaultId": "<string>",
  "opVaultAllowedDomains": [
    "<string>"
  ],
  "judge": {
    "context": "<string>"
  },
  "maxCostUsd": 1
}
'

import requests

url = "https://api.browser-use.com/api/v4/runs"

payload = {
    "task": "<string>",
    "outputSchema": {},
    "model": "gpt-6-luna",
    "modelParams": {},
    "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "browserSettings": {
        "profileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "proxyCountryCode": "us",
        "customProxy": {
            "host": "<string>",
            "port": 32768,
            "username": "<string>",
            "password": "<string>",
            "ignoreCertErrors": False
        },
        "screenWidth": 3232,
        "screenHeight": 1888,
        "allowResizing": True,
        "record": True,
        "extensionIds": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"]
    },
    "agentmail": False,
    "agentcardWalletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "stripeLinkConnectionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "attachedFileIds": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "secretBindings": [
        {
            "alias": "<string>",
            "source": {
                "type": "inline",
                "value": "<string>"
            },
            "allowedDomains": ["<string>"]
        }
    ],
    "opVaultId": "<string>",
    "opVaultAllowedDomains": ["<string>"],
    "judge": { "context": "<string>" },
    "maxCostUsd": 1
}
headers = {
    "X-Browser-Use-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "queued",
  "model": "<string>",
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "eventsUrl": "<string>",
  "missingFileIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "skippedVaultItems": [
    "<string>"
  ]
}

{
  "detail": "<string>"
}

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

POST

runs

Create Run

const options = {
  method: 'POST',
  headers: {'X-Browser-Use-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    task: '<string>',
    outputSchema: {},
    model: 'gpt-6-luna',
    modelParams: {},
    sessionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    workspaceId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    browserSettings: {
      profileId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
      proxyCountryCode: 'us',
      customProxy: {
        host: '<string>',
        port: 32768,
        username: '<string>',
        password: '<string>',
        ignoreCertErrors: false
      },
      screenWidth: 3232,
      screenHeight: 1888,
      allowResizing: true,
      record: true,
      extensionIds: ['3c90c3cc-0d44-4b50-8888-8dd25736052a']
    },
    agentmail: false,
    agentcardWalletId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    stripeLinkConnectionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    attachedFileIds: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    secretBindings: [
      {
        alias: '<string>',
        source: {type: 'inline', value: '<string>'},
        allowedDomains: ['<string>']
      }
    ],
    opVaultId: '<string>',
    opVaultAllowedDomains: ['<string>'],
    judge: {context: '<string>'},
    maxCostUsd: 1
  })
};

fetch('https://api.browser-use.com/api/v4/runs', 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/v4/runs \
  --header 'Content-Type: application/json' \
  --header 'X-Browser-Use-API-Key: <api-key>' \
  --data '
{
  "task": "<string>",
  "outputSchema": {},
  "model": "gpt-6-luna",
  "modelParams": {},
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "browserSettings": {
    "profileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "proxyCountryCode": "us",
    "customProxy": {
      "host": "<string>",
      "port": 32768,
      "username": "<string>",
      "password": "<string>",
      "ignoreCertErrors": false
    },
    "screenWidth": 3232,
    "screenHeight": 1888,
    "allowResizing": true,
    "record": true,
    "extensionIds": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ]
  },
  "agentmail": false,
  "agentcardWalletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "stripeLinkConnectionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "attachedFileIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "secretBindings": [
    {
      "alias": "<string>",
      "source": {
        "type": "inline",
        "value": "<string>"
      },
      "allowedDomains": [
        "<string>"
      ]
    }
  ],
  "opVaultId": "<string>",
  "opVaultAllowedDomains": [
    "<string>"
  ],
  "judge": {
    "context": "<string>"
  },
  "maxCostUsd": 1
}
'

import requests

url = "https://api.browser-use.com/api/v4/runs"

payload = {
    "task": "<string>",
    "outputSchema": {},
    "model": "gpt-6-luna",
    "modelParams": {},
    "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "browserSettings": {
        "profileId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "proxyCountryCode": "us",
        "customProxy": {
            "host": "<string>",
            "port": 32768,
            "username": "<string>",
            "password": "<string>",
            "ignoreCertErrors": False
        },
        "screenWidth": 3232,
        "screenHeight": 1888,
        "allowResizing": True,
        "record": True,
        "extensionIds": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"]
    },
    "agentmail": False,
    "agentcardWalletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "stripeLinkConnectionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "attachedFileIds": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "secretBindings": [
        {
            "alias": "<string>",
            "source": {
                "type": "inline",
                "value": "<string>"
            },
            "allowedDomains": ["<string>"]
        }
    ],
    "opVaultId": "<string>",
    "opVaultAllowedDomains": ["<string>"],
    "judge": { "context": "<string>" },
    "maxCostUsd": 1
}
headers = {
    "X-Browser-Use-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "queued",
  "model": "<string>",
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "eventsUrl": "<string>",
  "missingFileIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "skippedVaultItems": [
    "<string>"
  ]
}

{
  "detail": "<string>"
}

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

Authorizations

X-Browser-Use-API-Key

string

header

required

Body

application/json

task

string

required

Minimum string length: 1

outputSchema

Outputschema · object | null

Optional JSON Schema for the final output (API runs only).

model

enum<string>

default:gpt-6-luna

bu-ultrafast and bu-fast are early-access ultrafast presets; they take no modelParams and are rejected for projects without access.

Available options:

mimo-v2.6-pro,

mimo-v2.6-flash,

deepseek-v4.1-flash,

glm-5.2,

grok-4.5,

grok-4.6,

glm-5.3-flash,

deepseek-v4-flash-vision,

kimi-k3,

minimax-m3,

claude-opus-4.7,

claude-opus-4.8,

claude-opus-5,

claude-opus-5-5,

claude-fable-5,

claude-sonnet-5,

gpt-5.5,

gpt-5.6,

gpt-6-astra,

gpt-6-sol,

gpt-6.1-sol,

gpt-6-luna,

gpt-5.6-sol,

gpt-5.6-terra,

gpt-5.6-luna,

gemini-3.6-flash,

gemini-3.5-flash,

gemini-3.1-pro,

gemini-3-flash,

bu-ultrafast,

bu-fast

modelParams

Modelparams · object | null

Optional provider-native request parameters for the selected model, written with the provider's own field names and values and forwarded unchanged (e.g. {"reasoning": {"effort": "high"}} for OpenAI, {"thinking": {"type": "adaptive"}} for Anthropic, {"thinkingConfig": {"thinkingLevel": "high"}} for Google). Supported paths and values are per-model; an unsupported path, value, or a model that accepts no parameters at all is rejected with 422. Omitting this field applies the model's default parameters (gpt-6-luna defaults to {"reasoning": {"effort": "high"}}); passing {} opts out of that default and leaves the provider's own defaults in place.

sessionId

string<uuid> | null

workspaceId

string<uuid> | null

browserSettings

RunBrowserSettings · object | null

Browser config, owned by the browser row (never the run). Follow-ups: omitted fields inherit the session's prior browser; explicit values apply only to newly provisioned browsers (a live browser is reused as-is). Profile is the exception: a different profile → 400; an explicit value mismatching the live browser's profile (incl. null vs a profiled browser) declines reuse and provisions fresh. A live browser already matching the requested profile is reused. Extensions are session-wide: follow-ups inherit them, and a different set → 400 (see extensionIds).

Show child attributes

agentmail

boolean

default:false

If true, provisions a persistent temporary email inbox (via AgentMail) for the run workspace. The agent receives the email address in its context and can send, receive, read, and reply to email. Set false to disable AgentMail for this run.

agentcardWalletId

string<uuid> | null

stripeLinkConnectionId

string<uuid> | null

attachedFileIds

string<uuid>[] | null

Maximum array length: 20

secretBindings

SecretBinding · object[] | null

Credentials this run may use without ever seeing them. The agent can ask the server to type a binding by alias on one of its allowed domains; it cannot read the value. Bindings are not persisted past the run.

Maximum array length: 20

Show child attributes

opVaultId

string | null

A 1Password vault id whose items become typed secrets for this run. The project's connected 1Password integration is resolved server-side; no per-item ids are needed.

Maximum string length: 64

opVaultAllowedDomains

string[] | null

Hosts every credential from opVaultId may be typed into, e.g. ["amazon.com"]. Omit to derive each item's hosts from its own 1Password website entries; items with no website are then skipped and reported in skippedVaultItems. A host covers its subdomains, so 1Password's ExactDomain autofill setting is not honored either way.

judge

RunJudgeSettings · object | null

Opt-in LLM judgement of the finished run. Presence of this object turns the judge on (send {} for defaults); CP judges the run's trajectory after it goes terminal and surfaces the verdict as RunSummary.judgement (null until it lands). The judge's LLM call is billed to the run.

Show child attributes

maxCostUsd

Required range: x > 0

Response

Successful Response

string<uuid>

required

status

enum<string>

required

Available options:

queued,

dispatching,

running,

completed,

failed,

cancelled

model

string

required

sessionId

string<uuid>

required

workspaceId

string<uuid>

required

eventsUrl

string

required

missingFileIds

string<uuid>[]

skippedVaultItems

string[]

Titles of opVaultId items that hold a credential but no 1Password website, so deriving their domains left them with nowhere to be typed. The run still starts without them; add a website to the item or pass opVaultAllowedDomains.

Get Started

Endpoints

Create Run

Authorizations

Body

Response