Create Run

POST /runs

Create Run

JavaScript

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']
    },
    keepAlive: 7260,
    agentmail: false,
    agentcardWalletId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    stripeLinkConnectionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    agenticAutofillGrantId: '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));

200

{
  "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>"
  ]
}

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, claude-sonnet-5-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

keepAlive · integer | null

Seconds the session's browser stays open after its last run, so a follow-up run reuses the same page, never past the browser's 4 h lifetime. Default 120. Follow-up runs inherit the session's value; send a new value to change it or null to restore the default. Kept time is billed as browser time. Ignored (always 120) for free-tier and Zero Data Retention projects.

Required range: 120 <= x <= 14400

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

agenticAutofillGrantId · 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 · number string

Required range: x > 0

Response

200

application/json

Successful Response

id · 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.