---
title: "Create a Session"
method: POST
path: "/v1/sessions"
---

# Create a Session

`POST /v1/sessions`

## Request body

- object
  - `projectId` string — The Project ID. Can be found in [Settings](https://www.browserbase.com/settings). Optional - if not provided, the project will be inferred from the API key.
  - `extensionId` string — The uploaded Extension ID. See [Upload Extension](/reference/api/upload-an-extension).
  - `browserSettings` object
    - `context` object
      - `id` string, required — The Context ID.
      - `persist` boolean — Whether or not to persist the context after browsing. Defaults to `false`.
    - `extensionId` string — The uploaded Extension ID. See [Upload Extension](/reference/api/upload-an-extension).
    - `viewport` object
      - `width` integer — The width of the browser.
      - `height` integer — The height of the browser.
    - `blockAds` boolean — Enable or disable ad blocking in the browser. Defaults to `false`.
    - `solveCaptchas` boolean — Enable or disable captcha solving in the browser. Defaults to `true`.
    - `recordSession` boolean — Enable or disable session recording. Defaults to `true`.
    - `logSession` boolean — Enable or disable session logging. Defaults to `true`.
    - `advancedStealth` boolean — Advanced Browser Stealth Mode
    - `verified` boolean — Verified Browser Mode
    - `captchaImageSelector` string — Custom selector for captcha image. See [Custom Captcha Solving](/features/stealth-mode#custom-captcha-solving)
    - `captchaInputSelector` string — Custom selector for captcha input. See [Custom Captcha Solving](/features/stealth-mode#custom-captcha-solving)
    - `os` 'windows' | 'mac' | 'linux' | 'mobile' | 'tablet' — Operating system for stealth mode. Valid values: windows, mac, linux, mobile, tablet
    - `allowedDomains` string[] — An optional list of allowed domains for the session. If you pass one or more domains, Browserbase restricts top-level (main-frame) page navigations to the listed domains and their subdomains. For example, `example.com` also permits `www.example.com` and `a.b.example.com`, but not `notexample.com`. Matching is domain-based, not full-URL. An empty list (the default) disables the restriction entirely. Browserbase enforces only main-frame navigations; it does not block iframe/subframe loads or other in-page resource requests (images, scripts, XHR, etc.).
    - `ignoreCertificateErrors` boolean — Enable or disable ignoring of certificate errors in the browser. Defaults to `true`.
  - `timeout` integer — Duration in seconds after which the session will automatically end. Defaults to the Project's `defaultTimeout`.
  - `keepAlive` boolean — Set to true to keep the session alive even after disconnections. Available on the Hobby Plan and above.
  - `proxies` union — Proxy configuration. Can be true for default proxy, or an array of proxy configurations.
    - union[]
      - union
        - BrowserbaseProxyConfig
          - `type` 'browserbase', required — Type of proxy. Always use 'browserbase' for the Browserbase managed proxy network.
          - `geolocation` object — Geographic location for the proxy. Optional.
            - `city` string — Name of the city. Use spaces for multi-word city names. Optional.
            - `state` string — US state code (2 characters). Must also specify US as the country. Optional.
            - `country` string, required — Country code in ISO 3166-1 alpha-2 format
          - `domainPattern` string — Domain pattern for which this proxy should be used. If omitted, defaults to all domains. Optional.
        - ExternalProxyConfig
          - `type` 'external', required — Type of proxy. Always 'external' for this config.
          - `server` string, required — Server URL for external proxy. Required.
          - `domainPattern` string — Domain pattern for which this proxy should be used. If omitted, defaults to all domains. Optional.
          - `username` string — Username for external proxy authentication. Optional.
          - `password` string — Password for external proxy authentication. Optional.
        - NoneProxyConfig
          - `type` 'none', required — Type of proxy. Always 'none' for this config.
          - `domainPattern` string — Domain pattern for which this proxy should be used. If omitted, defaults to all domains. Optional.
    - boolean
  - `proxySettings` object — Supplementary proxy settings. Optional.
    - `caCertificates` string[] — The TLS certificate IDs to trust. Optional.
  - `region` 'us-west-2' | 'us-east-1' | 'eu-central-1' | 'ap-southeast-1' — The region where the Session should run.
  - `userMetadata` object — Arbitrary user metadata to attach to the session. To learn more about user metadata, see [User Metadata](/features/sessions#user-metadata).

## Response `201`

The request has succeeded and a new resource has been created as a result.

- object
  - `id` string, required
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required
  - `projectId` string, required — The Project ID linked to the Session.
  - `startedAt` string, date-time, required
  - `endedAt` string, date-time
  - `expiresAt` string, date-time, required
  - `status` 'PENDING' | 'RUNNING' | 'ERROR' | 'TIMED_OUT' | 'COMPLETED', required
  - `proxyBytes` integer, required — Bytes used via the [Proxy](/features/stealth-mode#proxies-and-residential-ips)
  - `keepAlive` boolean, required — Indicates if the Session was created to be kept alive upon disconnections
  - `contextId` string — Optional. The Context linked to the Session.
  - `region` 'us-west-2' | 'us-east-1' | 'eu-central-1' | 'ap-southeast-1', required — The region where the Session is running.
  - `userMetadata` object — Arbitrary user metadata to attach to the session. To learn more about user metadata, see [User Metadata](/features/sessions#user-metadata).
  - `connectUrl` string, uri, required — WebSocket URL to connect to the Session.
  - `seleniumRemoteUrl` string, uri, required — HTTP URL to connect to the Session.
  - `signingKey` string, required — Signing key to use when connecting to the Session via HTTP.

---

[API](https://skmtc.net/browserbase/apis/browserbase-api.md) · [All operations](https://skmtc.net/browserbase/apis/browserbase-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/browserbase/browserbase-api/versions/832b22144edf/schema)