> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

# browser

***

## Overview

Browser module for running browser automation from your backend.

This module creates remote browser sessions that you can control with a [Chrome DevTools Protocol (CDP)](https://chromedevtools.github.io/devtools-protocol/) client library such as [Playwright](https://playwright.dev/docs/api/class-browsertype#browser-type-connect-over-cdp) or [Puppeteer](https://pptr.dev/api/puppeteer.puppeteer.connect). Base44 doesn't store browser state, so each session is independent.

### Authentication modes

This module is only available to use with a client in [service role authentication mode](https://docs.base44.com/developers/references/sdk/getting-started/client.md#service-role) (`base44.asServiceRole.browser`), which means it can only be used in backend environments.

## Methods

### getSession()

> **getSession**(`options?`): `Promise`\<`BrowserSession`>

Creates a new remote browser session and returns its connection details.

Each call creates a fresh session, which uses credits from the workspace that owns the app. Each session is billed by the minute until it ends. An open session keeps running until its timeout expires. When you're done, call `end()` on the session. To end it from a different request, use [`endSession()`](#endsession).

#### Parameters

**options** `BrowserSessionOptions`

Optional session settings.

> [accordion] Properties
>
> **captureDebugArtifacts** `boolean`
>
> Whether Base44's browser provider records the session and keeps its diagnostic logs.
>
> You can't retrieve the recordings or logs through the SDK. Set this to `false` when the session shows sensitive data that shouldn't be recorded. Defaults to `true`.
>
> **sessionTimeoutSeconds** `number`
>
> Maximum lifetime of the session, in whole seconds.
>
> The session ends when the timeout expires, even if it's still in use. Base44 clamps the value to between `60` and `900` seconds. Defaults to `300`.

#### Returns

`BrowserSession`

Promise resolving to the new browser session. Rejects with a [`Base44Error`](https://docs.base44.com/developers/references/sdk/getting-started/work-with-sdk#error-handling) whose `code` is one of the values under [Throws](#throws).

> [accordion] Properties
>
> **sessionId** `string` *required*
>
> Opaque session identifier issued to your app.
>
> Pass it unchanged to [`endSession()`](#endsession) to end the session from a different request.
>
> **connectionUrl** `string` *required*
>
> Signed WebSocket URL for connecting to the browser over the Chrome DevTools Protocol (CDP).
>
> Treat the complete URL as a credential. Don't log it or send it to the frontend.
>
> **connectionScope** `"browser" | "page"` *required*
>
> Scope of the CDP connection.
>
> * `'browser'`: The socket controls the whole browser.
> * `'page'`: The socket controls a single page.
>
> **connectionExpiresAt** `string`
>
> ISO 8601 timestamp when the connection URL expires. Omitted when the provider doesn't expose it.
>
> **sessionExpiresAt** `string`
>
> ISO 8601 timestamp when the browser session expires. Omitted when the provider doesn't expose it.
>
> **end** `() =\> Promise\<void\>` *required*
>
> Ends the session. Equivalent to calling [`endSession()`](#endsession) with this session's ID.

#### Throws

* `insufficient_credits`: The workspace is out of credits.
* `rate_limited`: You created more than 100 sessions in the last minute.
* `browser_capacity_exceeded`: Browser capacity is temporarily unavailable.

#### Examples

```typescript Open a page in a remote browser with Playwright theme={null}
import { createClientFromRequest } from 'npm:@base44/sdk';
import { chromium } from 'npm:playwright-core';

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const session = await base44.asServiceRole.browser.getSession();

  try {
    const browser = await chromium.connectOverCDP(session.connectionUrl);
    const page = browser.contexts()[0]?.pages()[0] ?? (await browser.newPage());
    await page.goto('https://example.com');
    const title = await page.title();
    await browser.close();

    return Response.json({ title });
  } finally {
    await session.end();
  }
});
```

```typescript Turn off recordings and diagnostic logs theme={null}
const session = await base44.asServiceRole.browser.getSession({
  captureDebugArtifacts: false,
});

try {
  // Connect to session.connectionUrl and run your automation
} finally {
  await session.end();
}
```

***

### endSession()

> **endSession**(`sessionId`): `Promise`\<`void`>

Ends a browser session created by your app.

Use this when the session was created in a different request. Otherwise call `end()` on the session returned by [`getSession()`](#getsession). Ending a session that has already ended succeeds, so it's safe to call more than once.

#### Parameters

**sessionId** `string` *required*

The `sessionId` returned by [`getSession()`](#getsession).

#### Returns

`Promise<void>`

Promise that resolves when the session has ended. Rejects with a [`Base44Error`](https://docs.base44.com/developers/references/sdk/getting-started/work-with-sdk#error-handling) whose `code` is one of the values under [Throws](#throws-2).

#### Throws

`browser_session_not_found`: The session ID wasn't issued to your app.

#### Example

```typescript End a session from a later request, using the ID sent in the request body theme={null}
import { createClientFromRequest } from 'npm:@base44/sdk';

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const { sessionId } = await req.json();
  await base44.asServiceRole.browser.endSession(sessionId);

  return new Response(null, { status: 204 });
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.