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

# Get started

<Tip>
  Read [the Notte skill](https://notte.cc/skill.md) and follow its setup instructions when setting up Notte or building browser automation. This is the shared source for CLI setup, authentication, and the browser-to-code workflow.
</Tip>

[Source: node-sdk/src/session.ts](https://github.com/nottelabs/notte/blob/main/node-sdk/src/session.ts)

Sessions provide a managed browser lifecycle for automation. The `use()` callback starts the session and stops it when the callback finishes, including when it throws.

```typescript theme={null}
import { NotteClient } from 'notte-sdk';

const client = new NotteClient();

// The session is automatically stopped when the callback exits.
await client.Session({ idle_timeout_minutes: 2 }).use(async (session) => {
  const status = await session.status();
  console.log(status);
});
```

## Usage

See more operations on sessions:

<CardGroup cols={3}>
  <Card title="Scrape" icon="download" href="/typescript-sdk-reference/session/scrape">
    Scrape the current page.

    With `response_format` or `instructions`, the extracted data is returned
    directly and a failed extraction throws `ScrapeFailedError`. Pass
    `raiseOnFailure: false` to receive the `StructuredData` wrapper instead.
  </Card>

  <Card title="Observe" icon="telescope" href="/typescript-sdk-reference/session/observe">
    Observe the current page: the list of actions that can be taken, a
    screenshot and page metadata.

    The `perception_type` defaults to the session option (`fast`). A bare
    string argument is accepted as the perception type.
  </Card>

  <Card title="Execute" icon="shoe-prints" href="/typescript-sdk-reference/session/execute">
    Execute an action on the current page.

    When the action fails and `raiseOnFailure` is true (the default, see the
    session option), the structured `exception_detail` returned by the API is
    rehydrated into an `ActionExecutionError` whose `errorType` names the
    server-side error class. `captcha_solve` actions get a 100 s request
    timeout and are retried up to 3 times on HTTP 408.
  </Card>
</CardGroup>

## Parameters

Use the defaults or pass these options to `client.Session(options)`:

<ParamField body="wait_for_authentication" type={"boolean | undefined"}>
  Wait in the SDK for managed authentication on start(). Defaults to true; use() always waits.
</ParamField>

<ParamField body="auth_retry" type={"number | undefined"}>
  Additional server-side login attempts, from 0 to 2. Only sent with auth\_ids.
</ParamField>

<ParamField body="headless" type={"boolean | undefined"}>
  **deprecated:**

  Remote sessions always use the supported browser launch mode.
  Retained as a boolean so existing typed configuration still compiles.
  `true` is discarded; `false` raises a migration error when starting.
</ParamField>

<ParamField body="open_viewer" type={"boolean | undefined"}>
  Open the live viewer in the local default browser after the session starts.
  This is a local SDK option and is not sent to the API.
</ParamField>

<ParamField body="raiseOnFailure" type={"boolean | undefined"}>
  Default for `execute()`: throw `ActionExecutionError` when an action fails.
  The counterpart of `raise_on_failure` on `RemoteSession`. Defaults to true.
</ParamField>

<ParamField body="perception_type" type={"PerceptionType | undefined"}>
  Default perception type for `observe()`. Defaults to `fast`.
</ParamField>

<ParamField body="cookie_file" type={"string | undefined"}>
  JSON cookie file: loaded into the session on `start()` when it exists and
  appended with the session cookies on `stop()`.
</ParamField>

<ParamField body="storage" type={"RemoteFileStorage | undefined"}>
  File storage to attach to the session so agents can consume uploaded files.
</ParamField>

<ParamField body="solve_captchas" type={"boolean | undefined"}>
  Whether to try to automatically solve captchas
</ParamField>

<ParamField body="max_duration_minutes" type={"number | undefined"}>
  Maximum session lifetime in minutes (absolute maximum, not affected by activity).
</ParamField>

<ParamField body="idle_timeout_minutes" type={"number | undefined"}>
  Idle timeout in minutes. Session closes after this period of inactivity (resets on each operation).
</ParamField>

<ParamField body="proxies" type={"boolean | (NotteProxy | ExternalProxy | TailnetProxy)[] | undefined"}>
  List of custom proxies to use for the session. If True, the default proxies will be used.
</ParamField>

<ParamField body="browser_type" type={"\"chromium\" | \"chrome\" | \"chrome-nightly\" | \"chrome-turbo\" | undefined"}>
  The browser type to use. Supported values are chromium and chrome. chrome-nightly and chrome-turbo are legacy aliases for chrome.
</ParamField>

<ParamField body="user_agent" type={"string | null | undefined"}>
  The user agent to use for the session
</ParamField>

<ParamField body="chrome_args" type={"string[] | null | undefined"}>
  Overwrite the chrome instance arguments
</ParamField>

<ParamField body="viewport_width" type={"number | null | undefined"}>
  Viewport width in pixels (minimum 500). Set together with viewport\_height.
</ParamField>

<ParamField body="viewport_height" type={"number | null | undefined"}>
  Viewport height in pixels (minimum 500). Set together with viewport\_width.
</ParamField>

<ParamField body="aspect_ratio" type={"\"5:4\" | \"16:9\" | null | undefined"}>
  Viewport shape preset. When set, the backend fits the largest rectangle of this aspect ratio inside the sampled available screen area. Cannot be combined with explicit viewport\_width/viewport\_height.
</ParamField>

<ParamField body="cdp_url" type={"string | null | undefined"}>
  The CDP URL of another remote session provider.
</ParamField>

<ParamField body="screenshot_type" type={"\"raw\" | \"full\" | \"last_action\" | undefined"}>
  The type of screenshot to use for the session.
</ParamField>

<ParamField body="profile" type={"SessionProfile | null | undefined"}>
  Browser profile configuration for state persistence
</ParamField>

<ParamField body="web_bot_auth" type={"boolean | undefined"}>
  Whether to use web bot authentication.
</ParamField>

<ParamField body="extra_http_headers" type={"{ [key: string]: string; } | null | undefined"}>
  Extra HTTP headers to be sent with every request.
</ParamField>

<ParamField body="vault_id" type={"string | null | undefined"}>
  The vault to use for the session
</ParamField>

<ParamField body="auth_ids" type={"string[] | undefined"}>
  Managed Auth connection IDs to verify and, when necessary, authenticate inside this session. Initial verification runs before returning; when login is needed, the session returns as authenticating. Poll /sessions/\{id}/auth for readiness.
</ParamField>

<ParamField body="block_ads" type={"boolean | undefined"}>
  Block ads and trackers in managed browsers using Basic filtering. Set false to disable. Does not configure externally supplied CDP browsers.
</ParamField>

<ParamField body="advanced_stealth" type={"boolean | undefined"}>
  Enable Notte's highest-fidelity browser environment for sites with sophisticated bot detection. Available to approved workspaces.
</ParamField>

<ParamField body="demonstrate" type={"boolean | undefined"}>
  Whether to enable the Notte recorder extension for this session. The extension is installed but remains inactive when this is false.
</ParamField>

<Accordion title="Direct constructor reference">
  ```typescript theme={null}
  new Session(client: NotteClient, options?: SessionOptions): Session;
  ```

  <ParamField body="client" type={"NotteClient"} required />

  <ParamField body="options" type={"SessionOptions"}>
    Default:

    ```typescript theme={null}
    {}
    ```
  </ParamField>

  ## Related types

  * [SessionOptions](/typescript-sdk-reference/types/sessionoptions)
</Accordion>


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