STACK
MENU
DOCS / THE ACCOUNT / BROWSER

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.

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

prompt
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. Every tool is in the tool reference. To pay on a page, see Your own card.

Browser | Docs