> ## 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.

# Sessions

> Manage browser sessions

<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>

List, create, and operate on browser sessions.

## `notte sessions code`

Get Python script for session steps

| Flag | Description |
| - | - |
| `--session-id <string>` | Session ID (uses current session if not specified) |

## `notte sessions cookies`

Get all cookies for the session

| Flag | Description |
| - | - |
| `--session-id <string>` | Session ID (uses current session if not specified) |

## `notte sessions cookies-set`

Set cookies from a JSON file

| Flag | Description |
| - | - |
| `--file <string>` | JSON file containing cookies array (required) |
| `--session-id <string>` | Session ID (uses current session if not specified) |

## `notte sessions list`

List active sessions

| Flag | Description |
| - | - |
| `--all`, `-a` | Include stopped sessions |
| `--page <int>` | Page number (1-indexed) |
| `--page-size <int>` | Number of items per page |

## `notte sessions network`

Get network logs for the session

| Flag | Description |
| - | - |
| `--path <string>` | Output directory for downloaded files (defaults to temp directory) |
| `--session-id <string>` | Session ID (uses current session if not specified) |
| `--urls-only` | Only show download URLs without downloading |

## `notte sessions offset`

Get session offset info

| Flag | Description |
| - | - |
| `--session-id <string>` | Session ID (uses current session if not specified) |

## `notte sessions replay`

Download the replay video (MP4) for a session.

Examples:

```bash theme={null}
notte sessions replay                       # saves to temp directory
notte sessions replay --path replay.mp4    # saves to specified path
```

| Flag | Description |
| - | - |
| `--path <string>` | Output path for the replay video (defaults to temp directory) |
| `--session-id <string>` | Session ID (uses current session if not specified) |

## `notte sessions save-profile`

Save the running session's browser state (cookies, localStorage, sessionStorage) into a browser profile.

The session keeps running. Pass `--profile-id` to overwrite an existing profile, or `--name` to create a new one. With neither, the state is saved into the profile the session was started with.

| Flag | Description |
| - | - |
| `--name <string>` | Create a new profile with this name and save into it |
| `--profile-id <string>` | Existing profile to overwrite |
| `--session-id <string>` | Session ID (uses current session if not specified) |

## `notte sessions start`

Start a new browser session

| Flag | Description |
| - | - |
| `--advanced-stealth` | Enable Notte's highest-fidelity browser environment for sites with sophisticated bot detection. Available to approved workspaces. (API default: false) |
| `--aspect-ratio <string>` | 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. |
| `--auth-ids <strings>` | 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. (repeatable) |
| `--auth-retry <int>` | auth-retry (API default: 0) |
| `--block-ads` | Block ads and trackers in managed browsers using Basic filtering. Set false to disable. Does not configure externally supplied CDP browsers. (API default: true) |
| `--browser-type <string>` | The browser type to use. Supported values are chromium and chrome. chrome-nightly and chrome-turbo are legacy aliases for chrome. (API default: chromium) (chromium, chrome, chrome-nightly, chrome-turbo) |
| `--cdp-url <string>` | The CDP URL of another remote session provider. |
| `--chrome-args <strings>` | Overwrite the chrome instance arguments (repeatable) |
| `--demonstrate` | Whether to enable the Notte recorder extension for this session. The extension is installed but remains inactive when this is false. (API default: false) |
| `--extra-http-headers <string>` | Extra HTTP headers as JSON (e.g. '\{"Authorization": "Bearer xxx"}') |
| `--idle-timeout-minutes <int>` | Idle timeout in minutes. Session closes after this period of inactivity (resets on each operation). (API default: 3) |
| `--max-duration-minutes <int>` | Maximum session lifetime in minutes (absolute maximum, not affected by activity). (API default: 15) |
| `--no-solve-captchas` | Do not attempt to solve captchas automatically |
| `--profile-id <string>` | Profile ID to use for this session |
| `--profile-persist` | Whether to save browser state to profile on session close (API default: false) |
| `--proxy` | Use default proxies |
| `--proxy-country <string>` | Proxy country code (e.g. us, gb, fr). Selects a proxy on its own; do not combine with `--proxy` |
| `--proxy-external-password <string>` | External proxy password |
| `--proxy-external-server <string>` | External proxy server URL (e.g. [http://proxy:8080](http://proxy:8080)). Enables external proxy |
| `--proxy-external-username <string>` | External proxy username |
| `--proxy-tailnet-client-id <string>` | Tailnet OAuth client ID. Enables Tailscale proxy |
| `--proxy-tailnet-client-secret <string>` | Tailnet OAuth client secret |
| `--screenshot-type <string>` | The type of screenshot to use for the session. (API default: last\_action) (raw, full, last\_action) |
| `--solve-captchas` | Whether to try to automatically solve captchas (API default: true) |
| `--tunnel <notte tunnel up>` | Route public traffic through a saved tunnel (see notte tunnel up) |
| `--user-agent <string>` | The user agent to use for the session |
| `--vault-id <string>` | The vault to use for the session |
| `--viewport-height <int>` | Viewport height in pixels (minimum 500). Set together with viewport\_width. |
| `--viewport-width <int>` | Viewport width in pixels (minimum 500). Set together with viewport\_height. |
| `--wait-for-authentication` | SDK waiting preference. The API always verifies inline and returns authenticating when background login is needed; SDKs implement waiting through readiness polling. (API default: true) |
| `--web-bot-auth` | Whether to use web bot authentication. (API default: false) |

## `notte sessions status`

Get session status

| Flag | Description |
| - | - |
| `--auth` | Show managed authentication readiness and operations |
| `--session-id <string>` | Session ID (uses current session if not specified) |

## `notte sessions stop`

Stop the session

| Flag | Description |
| - | - |
| `--session-id <string>` | Session ID (uses current session if not specified) |

## `notte sessions viewer`

Open session viewer in browser

| Flag | Description |
| - | - |
| `--session-id <string>` | Session ID (uses current session if not specified) |

## `notte sessions workflow-code`

Export session steps as code

| Flag | Description |
| - | - |
| `--session-id <string>` | Session ID (uses current session if not specified) |


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