Skip to main content
POST
python

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

FlowPassword
Token URL
token

Headers

​
x-notte-request-origin
string | null
​
x-notte-sdk-version
string | null

Body

application/json
​
solve_captchas
boolean
default:true

Whether to try to automatically solve captchas

​
max_duration_minutes
integer
default:15

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

Required range: x <= 1440
​
idle_timeout_minutes
integer
default:3

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

Required range: x <= 30
​
proxies

List of custom proxies to use for the session. If True, the default proxies will be used.

​
browser_type
enum<string>
default:chromium

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

Available options:
chromium,
chrome,
chrome-nightly,
chrome-turbo
​
user_agent
string | null

The user agent to use for the session

​
chrome_args
string[] | null

Overwrite the chrome instance arguments

​
viewport_width
integer | null

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

Required range: x >= 500
​
viewport_height
integer | null

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

Required range: x >= 500
​
aspect_ratio
enum<string> | null

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.

Available options:
5:4,
16:9
​
cdp_url
string | null

The CDP URL of another remote session provider.

​
screenshot_type
enum<string>
default:last_action

The type of screenshot to use for the session.

Available options:
raw,
full,
last_action
​
profile
SessionProfile · object | null

Browser profile configuration for state persistence

​
web_bot_auth
boolean
default:false

Whether to use web bot authentication.

​
extra_http_headers
Extra Http Headers · object | null

Extra HTTP headers to be sent with every request.

​
vault_id
string | null

The vault to use for the session

​
auth_ids
string[]

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.

Maximum array length: 10
​
wait_for_authentication
boolean
default:true

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

​
auth_retry
integer
default:0
Required range: 0 <= x <= 2
​
block_ads
boolean
default:true

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

​
advanced_stealth
boolean
default:false

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

​
demonstrate
boolean
default:false

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

Response

Successful Response

​
session_id
string
required

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

​
idle_timeout_minutes
integer
required

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

​
created_at
string<date-time>
required

Session creation time

​
last_accessed_at
string<date-time>
required

Last access time

​
status
enum<string>
required
Available options:
active,
authenticating,
closed,
error,
timed_out
​
timeout_minutes
integer
required
deprecated
read-only
​
max_duration_minutes
integer
default:15

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

​
closed_at
string<date-time> | null

Session closing time

​
duration
string

Session duration

​
close_reason
enum<string> | null

Reason the session closed, if it is no longer active

Available options:
manual,
idle_timeout,
max_duration,
error,
unknown
​
steps
Steps · object[]

Steps of the session

​
error
string | null

Error message if the operation failed to complete

​
proxies
boolean
default:false

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

​
browser_type
enum<string>
default:chromium
Available options:
chromium,
chrome,
firefox,
chrome-nightly,
chrome-turbo
​
network_request_bytes
integer
default:0

Total byte usage for network requests.

​
network_response_bytes
integer
default:0

Total byte usage for network responses.

​
user_agent
string | null

The user agent to use for the session

​
viewport_width
integer | null

The width of the viewport

​
viewport_height
integer | null

The height of the viewport

​
solve_captchas
boolean | null

Whether to solve captchas.

​
cdp_url
string | null

The URL to connect to the CDP server.

​
viewer_url
string | null

The remote session viewer URL.

​
web_bot_auth
boolean
default:false

Whether to use web bot authentication.

​
auth_ids
string[]

Managed Auth connection IDs attached to this session.

​
system_hidden
boolean
default:false

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