> ## 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.

# Overview

> The whole API in one page: you run tasks. A run gives you back ids. Reuse the ids. That's it.

The entire platform is **three calls on one thing — a run.** Everything else is optional.

## The one noun: a run

A **run** is one task an agent does. You start a run, watch it finish, and optionally continue it. You never create sessions or browsers — a run gives you a `sessionId`, and files live on that conversation automatically (no workspace to manage — see [Files](/cloud/files)).

## The three verbs

<Steps>
  <Step title="Start a run">
    ```bash theme={null}
    POST /api/v1/agents/browser-use/runs   { "task": "..." }
    → { "id": "run_1", "sessionId": "ses_1", "status": "queued" }
    ```

    You get back a run id and a `sessionId` (to continue) — immediately. Files live on the conversation automatically; there's no workspace to handle.
  </Step>

  <Step title="Watch it finish">
    ```bash theme={null}
    GET /api/v1/agents/browser-use/runs/run_1   → { "status": "completed", "output": ... }
    ```

    Poll until `status` is `completed`, then read `result` (the answer string; `output` is only set for structured output). The SDK's `run()` waits for you.
  </Step>

  <Step title="Continue (optional)">
    ```bash theme={null}
    POST /api/v1/agents/browser-use/runs   { "task": "...", "session_id": "ses_1" }
    ```

    Pass the `session_id` back to keep the same thread of context.
  </Step>
</Steps>

That is the whole hot path. Three calls.

## The ids you get back (never create)

A run hands you ids. They aren't things you build — they're names for what the run already made:

| Id          | What it is                                          | How you use it                                                                                                              |
| ----------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `sessionId` | a name for this thread of runs (the "conversation") | pass it back to continue; files also live on it                                                                             |
| `browserId` | the browser the run used                            | shows up on `GET /runs/{id}` once provisioned (the browser is made in the background — it's **not** in the create response) |

Files live on the conversation automatically — you never handle a `workspace_id`. (A named [workspace](/cloud/files#sharing-files-across-conversations) exists only for sharing files across *different* conversations — advanced.)

<Note>
  There is no "create a session" or "create a workspace" step. The first run makes them and returns their ids. You only ever create **runs**.
</Note>

## Choosing an agent

Two agents. Omit it and you get `browser-use` (the common case).

* **`browser-use`** — browser tasks: navigate, click, extract. Fast, OSS.
* **`browsercode`** — code + browser: data processing, multi-step work.

Read [`GET /agents`](/cloud/choose-an-agent) if you (or your LLM) want to pick programmatically. That's the only "which agent" you ever need.

## Optional: setting things up first

You never need these on the hot path — a run makes what it needs. They exist only if you want to prepare something **before** running:

* **Pre-load files** before the first run → [create a workspace](/cloud/files#pre-load-files) and upload into it.
* **Save a login** to reuse → [create a browser profile](/cloud/create-profile).
* **Drive a browser yourself** over CDP (no agent) → [create a standalone browser](/cloud/create-browser).

If you're not doing one of those three things, ignore this section entirely.

## That's the whole model

> **You run tasks. A run gives you back ids (session, workspace). Reuse the ids to continue or add files. The browser is handled for you. Optional setup exists only for preparing something before you run.**

Start with the [Quickstart](/cloud/quickstart).