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

# Tasks

> Run AI browser automation tasks with structured output, configurable models, real-time streaming, cost controls, and natural language instructions.

A task is the core primitive. Describe what you want in plain text, the agent browses the web and returns the result.

## run()

Runs the task and returns a `TaskResult` with typed output.

<CodeGroup>
  ```python Python theme={null}
  from browser_use_sdk import AsyncBrowserUse

  client = AsyncBrowserUse()
  result = await client.run("What is the current price of Bitcoin?")
  print(result.output)   # "Bitcoin is currently $67,432..."
  print(result.id)       # task ID
  print(result.status)   # TaskStatus.FINISHED
  print(result.steps)    # list of TaskStepView
  ```

  ```typescript TypeScript theme={null}
  import { BrowserUse } from "browser-use-sdk";

  const client = new BrowserUse();
  const result = await client.run("What is the current price of Bitcoin?");
  console.log(result.output);  // "Bitcoin is currently $67,432..."
  console.log(result.id);      // task ID
  console.log(result.status);  // "finished"
  console.log(result.steps);   // TaskStepView[]
  ```
</CodeGroup>

## Structured output

Pass a schema to get validated, typed data back.

<CodeGroup>
  ```python Python theme={null}
  from browser_use_sdk import AsyncBrowserUse
  from pydantic import BaseModel

  class Stock(BaseModel):
      ticker: str
      price: float
      change_pct: float

  client = AsyncBrowserUse()
  result = await client.run(
      "Get the current stock price of NVDA from Yahoo Finance",
      output_schema=Stock,
  )
  print(result.output)  # Stock(ticker='NVDA', price=135.40, change_pct=2.3)
  ```

  ```typescript TypeScript theme={null}
  import { BrowserUse } from "browser-use-sdk";
  import { z } from "zod";

  const Stock = z.object({
    ticker: z.string(),
    price: z.number(),
    changePct: z.number(),
  });

  const client = new BrowserUse();
  const result = await client.run(
    "Get the current stock price of NVDA from Yahoo Finance",
    { schema: Stock },
  );
  console.log(result.output);  // { ticker: "NVDA", price: 135.40, changePct: 2.3 }
  ```
</CodeGroup>

## Streaming steps

Use `async for` to yield steps as the agent works.

<CodeGroup>
  ```python Python theme={null}
  from browser_use_sdk import AsyncBrowserUse

  client = AsyncBrowserUse()
  run = client.run("Find the cheapest flight from NYC to London on Google Flights")
  async for step in run:
      print(f"Step {step.number}: {step.next_goal}")
      print(f"  URL: {step.url}")

  print(run.result.output)  # final result after iteration
  ```

  ```typescript TypeScript theme={null}
  import { BrowserUse } from "browser-use-sdk";

  const client = new BrowserUse();
  const run = client.run("Find the cheapest flight from NYC to London on Google Flights");
  for await (const step of run) {
    console.log(`Step ${step.number}: ${step.nextGoal}`);
    console.log(`  URL: ${step.url}`);
  }

  console.log(run.result?.output);  // final result after iteration
  ```
</CodeGroup>

## Message streaming (v3)

In the BU Agent API, use `sessions.messages()` to poll the agent's message history while a task runs. This gives you the full conversation — user messages, assistant reasoning, and tool calls.

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from browser_use_sdk.v3 import AsyncBrowserUse

  client = AsyncBrowserUse()

  session = await client.sessions.create("Find the top story on Hacker News")
  session_id = str(session.id)

  seen = set()
  while True:
      s = await client.sessions.get(session_id)
      msgs = await client.sessions.messages(session_id, limit=100)

      for m in msgs.messages:
          if str(m.id) not in seen:
              seen.add(str(m.id))
              print(f"[{m.role}] {m.data[:200]}")

      if s.status.value in ("idle", "stopped", "error", "timed_out"):
          print(f"\nDone — {s.output}")
          break
      await asyncio.sleep(2)
  ```

  ```typescript TypeScript theme={null}
  import { BrowserUse } from "browser-use-sdk/v3";

  const client = new BrowserUse();

  const session = await client.sessions.create({
    task: "Find the top story on Hacker News",
  });
  const sessionId = session.id;

  const seen = new Set<string>();
  while (true) {
    const s = await client.sessions.get(sessionId);
    const msgs = await client.sessions.messages(sessionId, { limit: 100 });

    for (const m of msgs.messages) {
      if (!seen.has(m.id)) {
        seen.add(m.id);
        console.log(`[${m.role}] ${m.data.slice(0, 200)}`);
      }
    }

    if (["idle", "stopped", "error", "timed_out"].includes(s.status)) {
      console.log(`\nDone — ${s.output}`);
      break;
    }
    await new Promise((r) => setTimeout(r, 2000));
  }
  ```
</CodeGroup>

Use `after` and `before` cursors for pagination through large message histories.

## Files

Upload images, PDFs, documents, and text files (10 MB max) to sessions, and download output files from completed tasks.

### Upload a file

Get a presigned URL, then upload via PUT.

<CodeGroup>
  ```python Python theme={null}
  import httpx
  from browser_use_sdk import AsyncBrowserUse

  client = AsyncBrowserUse()
  session = await client.sessions.create()

  upload = await client.files.session_url(
      session.id,
      file_name="input.pdf",
      content_type="application/pdf",
      size_bytes=1024,
  )

  with open("input.pdf", "rb") as f:
      async with httpx.AsyncClient() as http:
          await http.put(upload.presigned_url, content=f.read(), headers={"Content-Type": "application/pdf"})

  result = await client.run("Summarize the uploaded PDF", session_id=session.id)
  ```

  ```typescript TypeScript theme={null}
  import { BrowserUse } from "browser-use-sdk";
  import { readFileSync } from "fs";

  const client = new BrowserUse();
  const session = await client.sessions.create();

  const upload = await client.files.sessionUrl(session.id, {
    fileName: "input.pdf",
    contentType: "application/pdf",
    sizeBytes: 1024,
  });

  await fetch(upload.presignedUrl, {
    method: "PUT",
    body: readFileSync("input.pdf"),
    headers: { "Content-Type": "application/pdf" },
  });

  const result = await client.run("Summarize the uploaded PDF", { sessionId: session.id });
  ```
</CodeGroup>

<Warning>
  Presigned URLs expire after 120 seconds. Max file size: 10 MB.
</Warning>

### Download task output files

<CodeGroup>
  ```python Python theme={null}
  result = await client.tasks.get(task_id)
  for file in result.output_files:
      output = await client.files.task_output(task_id, file.id)
      print(output.presigned_url)  # download URL
  ```

  ```typescript TypeScript theme={null}
  const result = await client.tasks.get(taskId);
  for (const file of result.outputFiles) {
    const output = await client.files.taskOutput(taskId, file.id);
    console.log(output.presignedUrl);
  }
  ```
</CodeGroup>

## Key parameters

| Parameter                  | Type              | Description                                                                                                                     |
| -------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `task`                     | `str`             | What you want the agent to do. 1-50,000 characters.                                                                             |
| `llm`                      | `str`             | Model override. Default: Browser Use 2.0. See [Models & Pricing](/cloud/pricing).                                               |
| `output_schema` / `schema` | Pydantic / Zod    | Schema for structured output.                                                                                                   |
| `session_id`               | `str`             | Reuse an existing session. Omit for auto-session.                                                                               |
| `start_url`                | `str`             | Initial page URL. Saves steps — send the agent directly there.                                                                  |
| `secrets`                  | `dict`            | Domain-specific credentials. See [Authentication](/cloud/guides/authentication).                                                |
| `allowed_domains`          | `list[str]`       | Restrict agent to these domains only.                                                                                           |
| `session_settings`         | `SessionSettings` | Proxy, profile, browser config. See [Sessions](/cloud/guides/sessions).                                                         |
| `flash_mode`               | `bool`            | Faster but less careful navigation.                                                                                             |
| `thinking`                 | `bool`            | Enable extended reasoning.                                                                                                      |
| `vision`                   | `bool \| str`     | Enable screenshots for the agent.                                                                                               |
| `highlight_elements`       | `bool`            | Highlight interactive elements on the page.                                                                                     |
| `system_prompt_extension`  | `str`             | Append custom instructions to the system prompt.                                                                                |
| `judge`                    | `bool`            | Enable quality judge to verify output.                                                                                          |
| `skill_ids`                | `list[str]`       | Skills the agent can use during the task.                                                                                       |
| `op_vault_id`              | `str`             | 1Password vault ID for auto-fill credentials and 2FA. See [Authentication](/cloud/guides/authentication#1password-integration). |
| `metadata`                 | `dict[str, str]`  | Custom metadata attached to the task.                                                                                           |