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

The three verbs

1. Start a run

   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.

2. Watch it finish

   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.

3. Continue (optional)

   POST /api/v1/agents/browser-use/runs   { "task": "...", "session_id": "ses_1" }
   

   Pass the session_id back to keep the same thread of context.

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 exists only for sharing files across different conversations — advanced.)

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.

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 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 and upload into it.
• Save a login to reuse → create a browser profile.
• Drive a browser yourself over CDP (no agent) → create a standalone 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.