Browser API

Use the browser surface when you need one of these three paths:

• direct browser automation from your application code,
• a recorded flow that replays a driven task without a model in the loop,
• a per-browser MCP endpoint that exposes the Browser Use toolset.

The old standalone client.browserAgents API has been removed. If you want a Console-managed agent to browse the web, attach the Browser Use system tool in Console and invoke that agent through client.agents.

Durable targets

browser_snapshot and browserSessions.snapshot() return [ref=e4]-style markers — cheap, but valid only for the snapshot that produced them; the browser renumbers them on the next one. Every action result also carries resolvedTarget: the same element described by role+name, testId, label, placeholder, text or selector, which is what still resolves after a re-render and is safe to persist. client.browserFlows rejects a step whose target is a bare ref.

Browser Profiles

Browser profiles are reusable parent containers. They hold the default session config, artifact bucket, and metadata used by browser sessions and browser-scoped MCP endpoints.

client.browsers.create(input)

Create a browser profile.

const browser = await client.browsers.create({
  name: 'research-browser',
  defaultSessionConfig: {
    headless: true,
    viewport: { width: 1440, height: 900 },
    idleTimeoutMs: 120000,
  },
});

client.browsers.list(query?)

List browser profiles. Supports status filtering.

client.browsers.get(idOrKey)

Fetch one browser profile by id or key.

client.browsers.update(idOrKey, input)

Update browser profile metadata, defaults, or status.

client.browsers.delete(idOrKey)

Delete a browser profile.

client.browsers.setProfile(idOrKey, storageState, fileName?)

Attach a signed-in profile so every session starts authenticated, instead of replaying credentials through a login form on each run. Pass a Playwright storageState export — from context.storageState(), or from browserSessions.exportProfile() after driving a login once by hand. It is encrypted server-side and never readable back; only the summary returned here is.

const state = JSON.parse(await fs.readFile('profile.json', 'utf8'));
const profile = await client.browsers.setProfile('research-browser', state, 'profile.json');
console.log(profile.cookieCount, profile.origins);

client.browsers.clearProfile(idOrKey)

Remove the attached signed-in profile.

Browser Sessions

Browser sessions are the direct automation surface. You create a session under a browser profile, drive it with discrete actions, and optionally persist screenshots or PDFs.

client.browserSessions.create(input)

const session = await client.browserSessions.create({
  browserId: browser.id,
  name: 'akbank-research',
});

client.browserSessions.action(sessionKey, action)

await client.browserSessions.action(session.sessionKey, {
  type: 'goto',
  url: 'https://www.akbank.com',
  waitUntil: 'networkidle',
});

Supported action shapes include:

• goto, click, hover, type, press
• select, check, upload, drag
• scroll, wait (supports text and loadState conditions)
• tab, back, forward, reload

client.browserSessions.snapshot(sessionKey)

Capture the current aria snapshot.

const snapshot = await client.browserSessions.snapshot(session.sessionKey);
console.log(snapshot.ariaSnapshot);

client.browserSessions.extract(sessionKey, input)

Extract text, HTML, or attributes from the current page.

const headings = await client.browserSessions.extract(session.sessionKey, {
  selector: 'h1',
  mode: 'text',
  multiple: true,
});

client.browserSessions.find(sessionKey, text, options?)

Locate visible text and get back a durable target for each hit — cheaper than another snapshot when you already know what you're looking for, and safe to save into a flow step.

const hits = await client.browserSessions.find(session.sessionKey, 'Sign in', { limit: 5 });

client.browserSessions.diagnostics(sessionKey)

Console messages, failed requests and the last dialog this session saw — use it when an action succeeded but the page didn't do what you expected.

client.browserSessions.exportProfile(sessionKey)

Export this session's cookies and origin storage as a Playwright storageState, ready to hand to browsers.setProfile().

const state = await client.browserSessions.exportProfile(session.sessionKey);
await client.browsers.setProfile(browser.id, state);

client.browserSessions.screenshot(sessionKey, input?)

Persist a screenshot artifact and get back its file reference.

client.browserSessions.screenshotLive(sessionKey, query?)

Fetch raw image bytes without persistence.

client.browserSessions.pdf(sessionKey, input?)

Export the page as a persisted PDF artifact.

client.browserSessions.list(query?)

List browser sessions. Supports status and browserId filters.

client.browserSessions.get(sessionId)

Fetch one session by id.

client.browserSessions.listEvents(sessionId, query?)

Read the stored event trail for a session. Supports limit and skip.

client.browserSessions.close(sessionKey)

Close a live session.

client.browserSessions.delete(sessionId)

Delete a stored session record.

Browser Flows

Driving a browser with a model is discovery — it reads the page, guesses, backtracks, and bills tokens for every step. A flow records that discovery once and replays it deterministically, with no model in the loop.

// 1. Drive a session however you like (agent, or by hand).
const session = await client.browserSessions.create({ browserId });
await client.browserSessions.action(session.sessionKey, { type: 'goto', url });
// …

// 2. Freeze it into a flow. Typed values become declared inputs —
//    the recorder cannot tell a search term from a password, so every
//    typed value is promoted rather than baked in as a literal.
const flow = await client.browserFlows.record({
  sessionId: session.id,
  name: 'Submit expense',
  status: 'active',
});

// 3. Replay it with different values, any number of times.
const run = await client.browserFlows.run(flow.key, {
  inputs: { reference: 'EXP-2002', amount: '999' },
});
console.log(run.status, run.outputs);

A failed run still resolves — inspect run.status, run.failedStepIndex and run.stepResults to see which step broke and why, rather than catching an exception.

client.browserFlows.create(input) / update(idOrKey, input) / delete(idOrKey)

Manage a flow's steps and metadata directly, without recording.

client.browserFlows.list(query?) / get(idOrKey)

List flows (filterable by status, browserId, search) or fetch one.

client.browserFlows.record(input)

Turn a driven session's action log into a replayable flow. Volatile ref targets are substituted for durable ones.

client.browserFlows.run(idOrKey, input?)

Run a flow and wait for the result.

client.browserFlows.listRuns(query?) / getRun(runId)

Run history, filterable by flowId and status.

Browser MCP

Every browser profile exposes its own MCP endpoint. This is the external transport equivalent of the Browser Use system tool, and its tool list is derived from the same definitions the agent binding uses.

client.browserMcp.getConnectionInfo(browserKey)

Build the browser-scoped MCP URLs.

const info = client.browserMcp.getConnectionInfo(browser.key);

console.log(info.sseUrl);
console.log(info.messageUrlTemplate);
// Authorization: Bearer <API_TOKEN>

client.browserMcp.getSseUrl(browserKey)

Get the SSE URL for an MCP client.

client.browserMcp.getMessageUrl(browserKey, sessionId)

Build the JSON-RPC message URL once your MCP client has a sessionId.

client.browserMcp.initialize(browserKey)

Read the MCP server metadata.

const meta = await client.browserMcp.initialize(browser.key);
console.log(meta.protocolVersion, meta.serverInfo.name);

client.browserMcp.listTools(browserKey)

List the Browser Use-compatible MCP tools exposed by the browser — 21 tools spanning navigation, form controls, tabs, find-by-text, diagnostics, artifacts, and flows.

const tools = await client.browserMcp.listTools(browser.key);
console.log(tools.map((tool) => tool.name));

Migration Note

If you previously depended on the removed browser agent management API:

1. Use client.browserSessions for direct programmatic browser automation.
2. Use client.browserFlows once a task has been driven once and should run unattended afterwards.
3. Use client.browserMcp when another MCP-compatible runtime should drive the browser.
4. Use Console-managed agents plus the Browser Use system tool when you want a hosted agent to browse autonomously.