> ## Documentation Index
> Fetch the complete documentation index at: https://browseruse-0aece648-larsen-v1-unified-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a task

> POST a task to an agent. One call starts a run; the run provisions whatever it needs and returns ids you can reuse.

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

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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);
  ```

  ```bash curl theme={null}
  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" }
    }'
  ```
</CodeGroup>

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

```json theme={null}
{
  "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](/cloud/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](/cloud/watch-a-run) until `status` is `completed` and read `result` (the answer string; `output` is only populated for [structured output](/cloud/agent/structured-output)). The SDK `run()` waits for you and returns the finished run.

## Run body

Common fields (full list in the [API reference](/cloud/api-v1-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](/cloud/use-a-profile)) |
| `session_id`        | string    | continue a previous run ([continue a task](/cloud/continue-a-task))                                                                                                        |
| `attached_file_ids` | string\[] | files to give this run (add them first via `POST /agents/{agent}/files` — see [Files](/cloud/files))                                                                       |
| `workspace_id`      | string    | **advanced**, `browsercode` only — an explicit workspace for cross-conversation sharing; omit on the normal path ([files](/cloud/files))                                   |

<Warning>
  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`.
</Warning>

<Note>
  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](/cloud/create-browser) instead — that's a different flow.
</Note>

## 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`:

<CodeGroup>
  ```python Python theme={null}
  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"]
  ```

  ```bash curl theme={null}
  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}]}"}'
  ```
</CodeGroup>

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

## browsercode

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

<CodeGroup>
  ```python Python theme={null}
  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
  ```

  ```bash curl theme={null}
  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"}'
  ```
</CodeGroup>