Session Start

POST /sessions/start

python

Python

from notte_sdk import NotteClient, actions

notte = NotteClient()
# the simple way: create a session that gets stopped automatically
with notte.Session() as session:
    _ = session.execute(
        actions.Goto(url="https://www.google.com")
    )

# for more control, start it manually
session = notte.Session()
session.start()

200

{
  "session_id": "<string>",
  "idle_timeout_minutes": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "last_accessed_at": "2023-11-07T05:31:56Z",
  "status": "active",
  "timeout_minutes": 123,
  "max_duration_minutes": 15,
  "closed_at": "2023-11-07T05:31:56Z",
  "duration": "<string>",
  "steps": [
    {}
  ],
  "error": "<string>",
  "proxies": false,
  "browser_type": "chromium",
  "use_file_storage": false,
  "network_request_bytes": 0,
  "network_response_bytes": 0,
  "user_agent": "<string>",
  "viewport_width": 123,
  "viewport_height": 123,
  "headless": true,
  "solve_captchas": true,
  "cdp_url": "<string>",
  "viewer_url": "<string>",
  "web_bot_auth": false
}

Authorizations

Authorization · string · header · required

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

Headers

x-notte-request-origin · string | null

x-notte-sdk-version · string | null

Body

application/json

headless · boolean · default: true

Whether to run the session in headless mode.

solve_captchas · boolean · default: false

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

proxies · (NotteProxy · object | ExternalProxy · object)[] boolean

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

NotteProxy

ExternalProxy

Show child attributes

browser_type · enum<string> · default: chromium

The browser type to use. Can be chromium, chrome or firefox.

Available options: chromium, chrome, firefox, 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

The width of the viewport

viewport_height · integer | null

The height of the viewport

cdp_url · string | null

The CDP URL of another remote session provider.

use_file_storage · boolean · default: true

Whether FileStorage should be attached to the session.

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

Browser profile configuration for state persistence

Show child attributes

web_bot_auth · boolean · default: false

Whether to use web bot authentication.

extra_http_headers · Extra Http Headers · object

Extra HTTP headers to be sent with every request.

Show child attributes

vault_id · string | null

The vault to use for the session

Response

200

application/json

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

Session status

Available options: active, 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<duration>

Session duration

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

use_file_storage · boolean · default: false

Whether FileStorage was attached to the session.

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

headless · boolean · default: true

Whether to run the session in headless mode.

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.