---
title: "Create a session"
method: POST
path: "/v1/sessions"
tags: ["sessions"]
---

# Create a session

`POST /v1/sessions`

## Headers

- `Authorization` string, required

## Request body

- object
  - `configuration` TypeSessionConfigV1
    - `baseProfileId` string — Deprecated: Use profileName instead.
    - `extensionIds` string[] — Google Web Store extension IDs to be loaded into the session.
    - `persistProfile` boolean — Deprecated: use Save Profile On Termination API instead.
    - `profileName` string — Name of a profile to load into the session.
    - `proxy` union — Proxy configuration.
      - boolean
      - union — Configuration for a single custom proxy.
        - string
        - TypeAirtopProxyConfiguration
          - `country` string — Country to exit from, in [ISO 3166-1 alpha-2 format](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). Or `global` to get IP addresses from random countries. We do not guarantee an available proxy in all countries.
          - `sticky` boolean — Try to maintain the same IP address for the duration for up to a maximum of 30 minutes. `true` by default. <Note>Stickiness is on a best-effort basis; we cannot guarantee that the same IP address will be available for 30 minutes at a time.</Note>
        - TypeProxyCredentials — Proxy object with url of the proxy as a parameter. Takes optional username and password.
          - `password` string
          - `url` string, required
          - `username` string
      - TypeProxyConfigurationKind[]
        - `domainPattern` string, required
        - `relay` union, required — Configuration for a single custom proxy.
          - string
          - TypeAirtopProxyConfiguration
            - `country` string — Country to exit from, in [ISO 3166-1 alpha-2 format](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). Or `global` to get IP addresses from random countries. We do not guarantee an available proxy in all countries.
            - `sticky` boolean — Try to maintain the same IP address for the duration for up to a maximum of 30 minutes. `true` by default. <Note>Stickiness is on a best-effort basis; we cannot guarantee that the same IP address will be available for 30 minutes at a time.</Note>
          - TypeProxyCredentials — Proxy object with url of the proxy as a parameter. Takes optional username and password.
            - `password` string
            - `url` string, required
            - `username` string
    - `record` boolean — Enable session recording.
    - `solveCaptcha` boolean — Automatically solve captcha challenges.
    - `timeoutMinutes` integer — Number of minutes of inactivity (idle timeout) after which the session will terminate. The idle timeout is reset when a user makes an incoming HTTP request, AI request, or new WebSocket connection to the session. Thus, when using drivers like Puppeteer, Selenium or Playwright, the timeout reset depends on the nature of the driver request. If not specified, defaults to 10 minutes.

## Response `201`

Created

- TypeSessionResponse
  - `data` TypeExternalSessionWithConnectionInfo, required
    - `cdpUrl` string — Url to connect to chrome devtools protocol port on the Airtop browser. Include the header 'Authorization: Bearer <api-key>.'
    - `cdpWsUrl` string — Websocket url to connect to the Airtop browser for CDP-based automation frameworks (e.g. Puppeteer or Playwright). Include the header 'Authorization: Bearer <airtop-api-key>.'
    - `chromedriverUrl` string — Websocket url to connect to the Airtop browser for webdriver-based automation frameworks (e.g. Selenium). Include the header 'Authorization: Bearer <airtop-api-key>.'
    - `configuration` TypeExternalSessionConfig, required
      - `baseProfileId` string — Id of a profile to load into the session.
      - `persistProfile` boolean — Persist the profile.
      - `timeoutMinutes` integer — Max length of session in minutes, after which it will terminate if not already deleted.
    - `currentUsage` integer — Current usage in minutes.
    - `dateCreated` string, date-time — Date the session was created.
    - `id` string, uuid, required — Id of the session.
    - `lastActivity` string, date-time — Date of the last activity.
    - `profileId` string — Id of a newly persisted profile. DEPRECATED: Use profileName.
    - `status` string, required — Session status.
    - `viceUrl` string — -
  - `errors` TypeIssue[]
    - `code` string — Issue code.
    - `details` object — Any associated details.
    - `message` string, required — Message describing the issue.
    - `reason` string — Underlying reason for the issue.
  - `meta` TypeEnvelopeDefaultMeta, required
    - `requestId` string
  - `warnings` TypeIssue[]
    - `code` string — Issue code.
    - `details` object — Any associated details.
    - `message` string, required — Message describing the issue.
    - `reason` string — Underlying reason for the issue.

---

[API](https://skmtc.net/airtop/apis/airtop-api.md) · [All operations](https://skmtc.net/airtop/apis/airtop-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/airtop/airtop-api/revisions/77d6e0f03453/schema)