Browser Automation (totalum-sdk/browser)

import … from 'totalum-sdk/browser' — or the same namespace on totalum from 'totalum-sdk'. Install, configuration and errors: Totalum SDK.

A real Chrome in the cloud, driven over HTTPS from your server, so it works inside the published app: open pages, click, type, log in, fill forms, download files, take screenshots and PDFs, extract data. Use it when a page needs interaction; to just read a page, totalum.web.scrape is cheaper and faster. Billed in credits per started minute of an open session: always close() the session in finally. Plans allow a few sessions at once (one on Free); a session with no call for 60 s is closed.

const s = await totalum.browser.session();
try {
  await s.goto('https://example.com');
  const title = await s.evaluate<string>('document.title');
} finally {
  await s.close();
}

#totalumBrowser

totalumBrowser(options?: TotalumClientOptions): TotalumBrowser

Creates the browser namespace (the same object as totalum.browser, scope browser): remote browser sessions driven entirely over HTTPS, so every command works from a Worker. A command's refusal throws TotalumError with its frozen code (ACTION_TIMEOUT, ACTION_FAILED, …); actions() returns every result instead.

#Things that still need a CDP connection

Nothing an app needs. Every capability is a command or a create-time option, so it works in a published app. The list keeps exactly two entries, neither of which an app needs:

• Attaching a raw CDP domain listener for a continuous event stream — network.subscribe is the push channel for the app case.
• Driving the session with a third-party Node library's own protocol client (connectOverCDP, puppeteer.connect).

#Not possible for anyone, over any transport

• Seeding a saved profile from raw bytes (CONTEXT_SEED_UNSUPPORTED) — the browser provider's profile upload is deprecated; create a profile by running a session with context: { persist: true }, and replay cookies and web storage with cookies.set and storage.set (a service worker or an IndexedDB database cannot be replayed).

Parameters

Returns TotalumBrowser — The browser namespace: the methods below.

Example

import { totalumBrowser } from 'totalum-sdk/browser';

const browser = totalumBrowser();
const s = await browser.session();
try {
  await s.goto('https://example.com');
} finally {
  await s.close();
}

The namespace's type is exported as TotalumBrowser (import type { TotalumBrowser } from 'totalum-sdk/browser').

#browser.session

browser.session(opts?: BrowserSessionInput): Promise<BrowserSession>

Opens a session. It returns the cloud browser's handle: call commands on it (s.goto(url), s.click(target), …) and close() it in finally. Billed per started minute while open. At most 3 sessions are open at once per project (1 on Free); one more waits in a queue up to 60 s. A session with no call for 60 s is closed; it lasts at most timeoutMinutes.

Totalum-synthesised options (Totalum applies them to every page, so the browser provider validates none of them): locale, timezone, geolocation, userAgent, extraHeaders, blockResources, device, captureDownloads, viewport. Mapped onto vendor fields: stealth ('off' | 'basic' | 'verified'; 'verified' needs a higher provider tier, else STEALTH_TIER_UNAVAILABLE, and ignores viewport) and region (four regions; 'eu' and 'us' are aliases). Every other option is passed to the browser provider as is.

Parameters

Returns Promise<BrowserSession> — The session handle.

Errors — besides the errors every call can throw:

Example

const s = await totalum.browser.session({ locale: 'es-ES', timezone: 'Europe/Madrid' });
try {
  await s.goto('https://example.com');
  const info = await s.pageInfo();
} finally {
  await s.close();
}

Result:

{
  id: 'bs_a285ef5dfce1d3837b913a887a384298',
  liveViewUrl: 'https://sdk-api.totalum.app/v1/browser/live/eyJzIjoiYnNfYTI4NWVm…',
  expiresAt: '2026-10-11T17:56:24.666Z',
  goto: [Function], click: [Function], …, close: [Function]
}

#browser.sessions.list

browser.sessions.list(q?: { status?, metadata?, limit?, cursor? }): Promise<{ items, nextCursor? }>

The project's sessions, newest first — open ones and the history — filtered by status or metadata. Free.

Parameters

Returns Promise<{ items, nextCursor? }> — One page of sessions.

Errors — besides the errors every call can throw:

Example

const { items } = await totalum.browser.sessions.list({ status: 'running', limit: 2 });

Result:

{
  "items": [
    { "id": "bs_20b6813a9f10ce41b3ff002d80e911c4", "status": "ended", "region": "us-west-2", "metadata": null, "startedAt": "2026-09-28T13:18:46.849Z", "expiresAt": "2026-09-28T13:33:46.244Z", "minutes": 1, "proxyMb": 0, "captchas": 0, "credits": 0.056 }
  ],
  "nextCursor": "1790600898279:bs_8cbb1dd693454f4fd82fedbfb9671d0c"
}

#browser.sessions.get

browser.sessions.get(id: string): BrowserSession

A handle on an existing session, to keep driving it from another request (the id was stored). No call is made; the first command fails with SESSION_EXPIRED if it has ended. Calling a command also keeps it from closing after 60 s idle.

Parameters

Returns BrowserSession — The session handle (liveViewUrl and expiresAt are empty: read status()).

Example

const s = totalum.browser.sessions.get(job.browserSessionId);
await s.click({ text: 'Next page' });

#browser.programs.get

browser.programs.get(programId: string): Promise<BrowserProgramStatus>

A program's status and, once finished, each step's result and the final variables. Free.

Parameters

Returns Promise<BrowserProgramStatus> — The program's status and results.

Errors — besides the errors every call can throw:

Example

const p = await totalum.browser.programs.get('bp_a285ef5dfce1d3837b913a887a384298_3982732f');

Result:

{
  "programId": "bp_a285ef5dfce1d3837b913a887a384298_3982732f",
  "sessionId": "bs_a285ef5dfce1d3837b913a887a384298",
  "status": "completed",
  "steps": [
    { "index": 0, "type": "goto", "ok": true, "data": { "url": "https://example.com/", "status": 200, "redirected": false } },
    { "index": 1, "type": "pageInfo", "ok": true, "data": { "url": "https://example.com/", "title": "Example Domain", … } }
  ],
  "vars": {},
  "startedAt": "2026-10-11T17:42:25.605Z",
  "endedAt": "2026-10-11T17:42:27.912Z",
  "credits": 0
}

#browser.programs.wait

browser.programs.wait(programId: string, opts?: { intervalMs?, timeoutMs? }): Promise<BrowserProgramStatus>

Polls a program until it leaves pending/running and returns it (the browser.program.completed webhook is the push alternative). Keep it within a request's time: programs run at most 60 s.

Parameters

Returns Promise<BrowserProgramStatus> — The finished program (or as it is when the timeout passed).

Errors — besides the errors every call can throw:

Example

const done = await totalum.browser.programs.wait(programId, { intervalMs: 1000 });

Result:

{ "programId": "bp_a285ef5dfce1d3837b913a887a384298_3982732f", "status": "completed", "steps": [ … ], "vars": {}, "credits": 0, … }

#BrowserActionsOutput

The answer of a batch of commands.

#BrowserCommand

One command for s.actions() or a program step: { type, …parameters } ({ type: "goto", url }, { type: "click", target }). The parameters are the command's (see the session commands table).

type BrowserCommand = Record<string, unknown>

#BrowserCommandResult

The result of one command in s.actions().

#BrowserCommands

The command methods of a session: one per command (goto, click, … tabs.new, network.har, …), named like the command; dotted commands are groups (s.tabs.new()). See the session commands table under BrowserSession.

#BrowserProgram

A program for s.program(): steps that run in the background on the session — data, never code.

#BrowserProgramStatus

A program's status and results, from browser.programs.get() and wait().

#BrowserSession type

An open cloud-browser session, from browser.session() or browser.sessions.get(id): its id and live view, the methods below, and one method per command (the table below). Each method is one HTTPS call. Always close() it in finally: an open session is billed per minute until it closes (or until 60 s pass with no call).

#s.actions

s.actions(batch: BrowserCommand[], opts?: { stopOnError? }): Promise<BrowserCommandResult[]>

Runs up to 20 commands in one round trip, in order, under the session's lock, and returns every result instead of throwing: faster than one call per command. With stopOnError (the default), the commands after a failure are not run and answer SKIPPED.

Parameters

Returns Promise<BrowserCommandResult[]> — One result per command, in order: { ok: true, data } or { ok: false, error: { code, message } }.

Each item:

Errors — besides the errors every call can throw:

Example

const results = await s.actions([
  { type: 'goto', url: 'https://example.com' },
  { type: 'evaluate', expression: '1 + 1' },
]);

Result:

[
  { "ok": true, "data": { "url": "https://example.com/", "status": 200, "redirected": false } },
  { "ok": true, "data": 2 }
]

#s.program

s.program(program: BrowserProgram): Promise<{ programId, status, pollUrl }>

Starts a program on the session: a list of steps (commands, plus bounded repeat, if, try and set) that runs in the background — data, never code — so a long task outlives the request. Read it with browser.programs.get(programId) / programs.wait, or receive the browser.program.completed webhook.

Parameters

Returns Promise<{ programId, status, pollUrl }> — The program id and where to poll it.

Errors — besides the errors every call can throw:

Example

const { programId } = await s.program({
  steps: [
    { do: { type: 'goto', url: 'https://example.com' } },
    { do: { type: 'pageInfo' } },
  ],
});
const done = await totalum.browser.programs.wait(programId);

Result:

{ "programId": "bp_a285ef5dfce1d3837b913a887a384298_3982732f", "status": "pending", "pollUrl": "https://sdk-api.totalum.app/v1/browser/programs/bp_a285ef5dfce1d3837b913a887a384298_3982732f" }

#s.status

s.status(): Promise<BrowserSessionStatus>

The session's state and what it has used so far (minutes, proxy MB, CAPTCHAs, credits). Also keeps an idle session open: a session with no call for 60 s is closed.

Returns Promise<BrowserSessionStatus> — The session's status.

Errors — besides the errors every call can throw:

Example

const status = await s.status();

Result:

{ "id": "bs_a285ef5dfce1d3837b913a887a384298", "status": "running", "startedAt": "2026-10-11T17:41:24.666Z", "minutes": 1, "proxyMb": 0, "captchas": 0, "credits": 0.1647, "expiresAt": "2026-10-11T17:56:24.666Z" }

#s.close

s.close(): Promise<{ minutes, proxyMb, captchas, creditsUsed, recordingUrl? }>

Ends the session and settles its charge. Always call it in finally: an open session is billed per started minute.

Returns Promise<{ minutes, proxyMb, captchas, creditsUsed, recordingUrl? }> — What the session used and cost.

Errors — besides the errors every call can throw:

Example

const closed = await s.close();

Result:

{ "minutes": 2, "proxyMb": 0, "captchas": 0, "creditsUsed": 0.279 }

#Session commands

Every command is a method of the session, named like the command (dotted names are groups: s.tabs.new()). The leading arguments are the command's main parameters; the last argument is an object with the rest of them. Every command also takes frame (a frame id from frames.list), tabId (a tab id from tabs.list) and timeoutMs (default 30 s; waitFor, pdf and extract up to 60 s, captcha.solve up to 120 s) in that last object. Each resolves to the command's result; a refusal throws TotalumError with the command's code. target is a CSS selector ('#email'), { text: 'Sign in' }, { role: 'button', name: 'Search' } or { xpath: '//button' }. Files a command produces (screenshots, PDFs, HAR files, downloads) are private files of the project: url is a signed link valid for 1 hour; keep the key and read it later with totalum.files.getSignedUrl(key).

#BrowserSessionCreated

A session just opened (what browser.session() reads to build its handle).

#BrowserSessionInput

The options of browser.session(); all optional.

#BrowserSessionStatus

A session's state and usage, from s.status().