Run a task

A run is one task. You create runs — nothing else. A run automatically gets a browser, a session (for follow-ups), and a workspace (for files) as needed, and returns their ids.

Start a run

from browser_use import BrowserUse

client = BrowserUse()
run = client.agents.browser_use.run(
    task="Find the cheapest direct flight SFO to Tokyo next month",
    browser={"proxy_country_code": "us"},   # optional
)
print(run.result)   # the answer string (`output` is only set for structured output)
print(run.session_id)   # pass this back to continue (see Continue a task)

import { BrowserUse } from "browser-use";

const client = new BrowserUse();
const run = await client.agents.browserUse.run({
  task: "Find the cheapest direct flight SFO to Tokyo next month",
  browser: { proxy_country_code: "us" },
});
console.log(run.result); // the answer string (`output` is only set for structured output)
console.log(run.sessionId);

curl -X POST https://api.browser-use.com/api/v1/agents/browser-use/runs \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Find the cheapest direct flight SFO to Tokyo next month",
    "browser": { "proxy_country_code": "us" }
  }'

The raw endpoint returns immediately (the run is async):

{
  "id": "run_abc123",
  "status": "queued",
  "sessionId": "ses_xyz789",
  "stepsUrl": "/api/v1/agents/browser-use/runs/run_abc123/steps",
  "missingFileIds": []
}

You get sessionId (to continue) right away; files live on that conversation automatically (no workspace id to handle — see Files). The browser is provisioned in the background — its browserId is not in this response; it appears on GET /runs/{id} once ready. Then watch the run until status is completed and read result (the answer string; output is only populated for structured output). The SDK run() waits for you and returns the finished run.

Run body

Common fields (full list in the API reference):

Field	Type	Notes
`task`	string	required — what to do, in plain language
`model`	string	LLM to use (optional; sensible default)
`browser`	object	`{ proxy_country_code, screen_width, screen_height, profile_id }` — provisions a browser for this run; `profile_id` starts it logged-in (profiles)
`session_id`	string	continue a previous run (continue a task)
`attached_file_ids`	string[]	files to give this run (add them first via `POST /agents/{agent}/files` — see Files)
`workspace_id`	string	advanced, `browsercode` only — an explicit workspace for cross-conversation sharing; omit on the normal path (files)

There is no top-level browser_profile_id on a run — pass it inside browser ({"browser": {"profile_id": "..."}}). And there is no structured_output request field yet: completed runs have a typed output field in the response, but the request parameter is not accepted by the API today (422 Extra inputs are not permitted). To get structured data now, describe the exact JSON shape you want in the task text and parse result.

A run provisions its browser. It does not accept an existing browser_id. If you want to drive a browser yourself over CDP, create a standalone browser instead — that’s a different flow.

Structured output

There is no structured_output request parameter yet — sending one returns 422 "Extra inputs are not permitted". Until it ships, get structured data by describing the exact JSON shape in the task text and parsing result:

import json

run = client.agents.browser_use.run(
    task=(
        "Get the top 3 Hacker News posts. Return ONLY a JSON object, no prose: "
        '{"posts": [{"title": str, "points": int}]}'
    ),
)
posts = json.loads(run.result)["posts"]

curl -X POST https://api.browser-use.com/api/v1/agents/browser-use/runs \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "Get the top 3 Hacker News posts. Return ONLY a JSON object, no prose: {\"posts\": [{\"title\": str, \"points\": int}]}"}'

The run response reserves a typed output field for native structured output; it is null until the request-side schema parameter is released.

browsercode

Same shape, different agent — for code + files + terminal work:

run = client.agents.browsercode.run(
    task="Scrape the prices from this catalog and save them to prices.csv",
)
# get the output file: client.agents.browsercode.runs.files(run.id, kind="output") — see Files

curl -X POST https://api.browser-use.com/api/v1/agents/browsercode/runs \
  -H "X-Browser-Use-API-Key: $BROWSER_USE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "Scrape the prices from this catalog and save them to prices.csv"}'

Get started

Agents

Browsers

Account

More

Start a run

Run body

Structured output

browsercode

​Start a run

​Run body

​Structured output

​browsercode

Start a run

Run body

Structured output

browsercode