# Browser

How an agent opens a page in its cloud browser, clicks and types on it, reads it and ends the session. What the browser is and what it costs is on [Services](/services).

## Before you start

The agent needs an open account whose browser is `ready`, and its Passport. Only the account's own agent uses its browser. There are no terminal commands for the browser: it is used from an AI client or from code.

## Open a page

```text
Open example.com in the browser and tell me what the page says.
```

The client calls `stack_start_browser_session`, `stack_browser_navigate` and `stack_browser_read`. From code:

```typescript
const browser = stack.accounts.browser;
const session = await browser.startSession('acct_123', { passportToken });

await browser.navigate('acct_123', session.session_id, { url: 'https://example.com' }, { passportToken });
const page = await browser.read('acct_123', session.session_id, { passportToken });
// page.url, page.title, page.text
```

- Only public http and https pages open. A private or local address is refused.
- read returns the address, the title, the text and the page's structure. The text is cut at 20,000 characters.
- stack_browser_screenshot returns the page as a JPEG.

Page text is content from outside. It is scanned and flagged on every account. With controls on, flagged text is withheld from the agent.

## Click, type, select, press

```typescript
await browser.act('acct_123', session.session_id,
  { action: 'click', target: { role: 'link', name: 'Sign up' } }, { passportToken });

await browser.act('acct_123', session.session_id,
  { action: 'type', target: { label: 'Email' }, value: 'assistant@example.com' }, { passportToken });

await browser.act('acct_123', session.session_id,
  { action: 'press', key: 'Enter' }, { passportToken });
```

- The tool is stack_browser_act. One call is one click, type, select or press.
- A target is found by its role and name, its visible text, its label, or a selector. Text, names and labels match as a case-insensitive part of the text unless exact is true, and the target must match exactly one visible element; otherwise the call fails within seconds and says what was not found and why.
- A value typed into a password field, or marked sensitive, is not recorded.
- A card number cannot be typed. Paying is the checkout, in Your own card.

## End the session

```typescript
await browser.endSession('acct_123', session.session_id);
```

The tool is `stack_end_browser_session`. A session also ends by itself at its length: 30 minutes unless the start names another with `max_minutes` (`maxMinutes` in the SDK), from 1 to 360. Time is reserved for that length at the start, and what was not used is given back at the end. An account can have any number of sessions open.

## What counts as an action

Starting a session, opening a page and each click, type, select or press are one action each. Reading, a screenshot and ending are free. Browser time is charged from credit by the minute, after the minutes the plan includes.

## When it is refused

- 403 BROWSER_URL_REFUSED - the address is private or local, or the page redirected to one.
- 409 BROWSER_SESSION_NOT_ACTIVE - the session has ended. Start a new one.
- 409 BROWSER_SESSION_ELSEWHERE - retry the same call.
- 422 BROWSER_ACTION_FAILED - the click or the typing did not complete on the page.
- 503 PROVIDER_CAPACITY_UNAVAILABLE - no browser is free right now. Nothing was charged.
- 503 BROWSER_SESSION_LENGTH_REFUSED - a session of that length cannot be started right now. Nothing was charged. Ask for a shorter one.
- 503 BROWSER_TIME_USED_UP - the browser time for the month is used up.
- 403 CONTROL_DENIED - with controls on, your policy or your own server refused it. Controls are asked as browser.session.start and browser.navigate, the second with the site and path only.

## Reference

Every field is on [Workspace and Browser](/docs/api/account-workspace-browser). Every tool is in the [tool reference](/docs/mcp-tools). To pay on a page, see [Your own card](/docs/account/card).
