NOnotte
sessions

Session Start

Changed on
post/sessions/start

Request

  • Base URL
    https://api.notte.cc (the document declares no server; this is the origin it was published from)
  • Auth
    OAuth 2
    Password
    Token URL: token

Headers

x-notte-request-originstring nullable
x-notte-sdk-versionstring nullable

Request body

solve_captchasboolean

Whether to try to automatically solve captchas

max_duration_minutesinteger

Maximum session lifetime in minutes (absolute maximum, not affected by activity).

idle_timeout_minutesinteger

Idle timeout in minutes. Session closes after this period of inactivity (resets on each operation).

browser_type'chromium' | 'chrome' | 'chrome-nightly' | 'chrome-turbo'

The browser type to use. Supported values are chromium and chrome. chrome-nightly and chrome-turbo are legacy aliases for chrome.

user_agentstring nullable

The user agent to use for the session

chrome_argsstring[] nullable

Overwrite the chrome instance arguments

viewport_widthinteger nullable

Viewport width in pixels (minimum 500). Set together with viewport_height.

viewport_heightinteger nullable

Viewport height in pixels (minimum 500). Set together with viewport_width.

aspect_ratio'5:4' | '16:9' nullable

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.

cdp_urlstring nullable

The CDP URL of another remote session provider.

web_bot_authboolean

Whether to use web bot authentication.

extra_http_headersobject nullable

Extra HTTP headers to be sent with every request.

vault_idstring nullable

The vault to use for the session

auth_idsstring[]

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.

wait_for_authenticationboolean

SDK waiting preference. The API always verifies inline and returns authenticating when background login is needed; SDKs implement waiting through readiness polling.

record_sessionboolean

Save session replay. False permanently disables saved replay; Live View remains available.

log_sessionboolean

Save browser session logs. False permanently disables saved logs, without disabling metering.

auth_retryinteger
block_adsboolean

Block ads and trackers in managed browsers using Basic filtering. Set false to disable. Does not configure externally supplied CDP browsers.

advanced_stealthboolean

Enable Notte's highest-fidelity browser environment for sites with sophisticated bot detection. Available to approved workspaces.

screenshot_type'raw' | 'full' | 'last_action'

Ignored since notte 1.10: screenshots are returned without highlighting.

demonstrateboolean

Whether to enable the Notte recorder extension for this session. The extension is installed but remains inactive when this is false.

Response

Successful Response

record_sessionboolean

Whether saved session replay is enabled. Defaults to true.

log_sessionboolean

Whether saved browser session logs are enabled. Defaults to true.

session_idstring required

The ID of the session (created or existing). Use this ID to interact with the session for the next operation.

idle_timeout_minutesinteger required

Session idle timeout in minutes. Will timeout if now() > last access time + idle_timeout_minutes

max_duration_minutesinteger

Session max duration in minutes. Will timeout if now() > creation time + max_duration_minutes

created_atstring date-time required

Session creation time

closed_atstring date-time nullable

Session closing time

last_accessed_atstring date-time required

Last access time

durationstring

Session duration

status'active' | 'authenticating' | 'closed' | 'error' | 'timed_out' required
close_reason'manual' | 'idle_timeout' | 'max_duration' | 'error' | 'unknown' nullable

Reason the session closed, if it is no longer active

stepsobject[]

Steps of the session

errorstring nullable

Error message if the operation failed to complete

proxiesboolean

Whether proxies were used for the session. True if any proxy was applied during session creation.

browser_type'chromium' | 'chrome' | 'firefox' | 'chrome-nightly' | 'chrome-turbo'
network_request_bytesinteger

Total byte usage for network requests.

network_response_bytesinteger

Total byte usage for network responses.

user_agentstring nullable

The user agent to use for the session

viewport_widthinteger nullable

The width of the viewport

viewport_heightinteger nullable

The height of the viewport

solve_captchasboolean nullable

Whether to solve captchas.

cdp_urlstring nullable

The URL to connect to the CDP server.

playwright_urlstring nullable

The WebSocket URL for Playwright's chromium.connect(), when supported by the server. Requires a matching Playwright client version. This is a live browser connection, not a replay URL.

viewer_urlstring nullable

The remote session viewer URL.

web_bot_authboolean

Whether to use web bot authentication.

auth_idsstring[]

Managed Auth connection IDs attached to this session.

system_hiddenboolean

Whether this session is an internal system run. Internal system runs are omitted from session.list() unless include_system=True is requested.

timeout_minutesinteger required

Changes

  • 604cdfbc3693Revision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

  • 4d05dac78797Revision changes
    • info

      request property deprecated