# Create session task ## OpenAPI Specification ```yaml openapi: 3.0.1 info: title: '' description: '' version: 1.0.0 paths: /api/v2/browser: get: summary: Create session task deprecated: false description: '' tags: - Scraping Browser parameters: - name: token in: query description: '' required: true example: '{{token}}' schema: type: string - name: sessionTTL in: query description: >- The session_ttl parameter controls the duration of the session and automatically closes the browser instance after the session times out. The unit of session_ttl is seconds (S), with a default value of 180 seconds (i.e., 3 minutes), and can be customized between 60 seconds (1 minute) and 900 seconds (15 minutes). When the specified TTL time is reached, the session will become invalid, and Scraping Browser will close the browser instance to release resources. Please set the session_ttl reasonably according to the task requirements to ensure that the operations are completed before the session times out. required: true example: '180' schema: type: string - name: sessionName in: query description: >- Set a name for your session to facilitate searching and viewing in the historical session list. required: false schema: type: string - name: sessionRecording in: query description: >- Whether to enable session recording. When enabled, the entire browser session execution process will be automatically recorded, and after the session is completed, it can be replayed and viewed in the historical session list details. required: false schema: type: boolean default: false - name: proxyURL in: query description: >- Used to set the browser’s proxy URL, for example: http://user:pass@ip:port. If this parameter is set, all other proxy* parameters will be ignored. Required if `proxyCountry` not set. > 💡Custom proxy functionality is currently only available to subscribers. [Upgrade here](https://www.scrapeless.com/en/pricing) required: true schema: type: string - name: proxyCountry in: query description: >- The proxyCountry parameter is used to set the target country of the proxy, making the request sent through the IP address of that region. You can customize the proxy source by specifying a country code for proxyCountry (e.g., US for the United States, GB for the United Kingdom, ANY for any country). Scraping Browser will provide the corresponding IP address based on the specified country, which helps meet regional access restrictions or geographic positioning needs. Required if `proxyURL` not set. required: true example: - AU schema: type: array items: type: string - name: proxyState in: query description: >- Specifies the target state/province within the selected country for more granular proxy routing. Must be used in conjunction with `proxyCountry`. Accepts state codes (e.g., `CA` for California, `NY` for New York). Available for select countries with defined state/province divisions. [learn mor](https://docs.scrapeless.com/en/proxies/features/proxy) required: false example: NSW schema: type: string - name: proxyCity in: query description: >- Specifies the target city within the selected state/province for city-level proxy routing. Must be used in conjunction with `proxyCountry` and `proxyState`. Provides the most precise geographic targeting. Availability depends on proxy infrastructure in specific cities. required: false example: sydney schema: type: string - name: extensionIds in: query description: >- setup browser extension by extension id, separate by comma for multiple extensions required: false schema: type: string - name: fingerprint in: query description: >- Custom browser fingerprint with URL encoded JSON string format, see below for full schema. note that the`ws/get`type of request cannot have a request body, the`Body Params`below only for display purpose required: false example: '' schema: user_agent: custom userAgent platform: Windows kernel_milestone: '135' localization: Localization: based_on_ip: false locale: en timezone: Asia/Shanghai languages: - en screen: width: 1920 height: 1080 args: {} type: string - name: profileId in: query description: >- Once a profile is created, you can add it to a new session to reuse its data. Assign the profile by including the profileId in your session configuration. required: false schema: type: string requestBody: content: application/json: schema: type: object properties: fingerprint: type: object properties: platform: type: string description: >- Specifies the return value of the JavaScript navigator.platform property, indicating the operating system type of the runtime environment. Optional values are “Windows”, “macOS”, or “Linux”. This parameter will be used for feature detection and the enabling judgment of system-related functions. Default value: Windows localization: type: object properties: timezone: type: string description: >- A time zone identifier conforming to the IANA time zone database format (e.g., `Asia/Shanghai`), controlling the default time zone behavior of JavaScript date objects and Intl.DateTimeFormat output, which is a key component of the time zone fingerprint. Default value: `America/New_York` languages: type: array items: type: string description: >- The browser’s supported language priority list, mapped to the navigator.languages property and the HTTP Accept-Language request header, determining the website’s content language selection logic. Default value: `en, en-US` basedOnIP: type: boolean description: >- Whether to automatically set timezone and languages based on IP. x-apidog-orders: - basedOnIP - timezone - languages description: browser localizations screen: type: object properties: width: type: integer description: screen width height: type: integer description: screen height x-apidog-orders: - width - height description: >- Defines the physical characteristics parameters of the display device reported by the browser, directly mapped to the JavaScript window.screen object. userAgent: type: string description: >- Defines the User-Agent string in the browser’s HTTP request header, containing key identifying information such as the browser engine, version number, and operating system. Websites use this value to identify the client environment, affecting content adaptation and functionality. Default value: Follows the browser args: type: object properties: {} x-apidog-orders: [] description: >- Run browser with command-line switches(e.g., `--window-size`, `--proxy-bypass-list`, etc, [learn more](https://www.chromium.org/developers/how-tos/run-chromium-with-flags/)), Please note that the following args are not supported: `--load-extension, --user-data-dir, --fonts-dir, --remote-debugging-port` x-apidog-orders: - userAgent - platform - screen - localization - args x-apidog-orders: - fingerprint example: userAgent: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.1.2.3 Safari/537.36 platform: Windows screen: width: 1920 height: 1080 localization: basedOnIP: false timezone: America/New_York languages: - en responses: '200': description: '' content: application/json: schema: type: object properties: success: type: boolean description: if task created taskId: type: string description: session taskId required: - success - taskId x-apidog-orders: - success - taskId example: success: true taskId: 10ed0c19-a002-45fa-866f-dc853d246da3 headers: {} x-apidog-name: Success security: - apikey-header-x-api-token: [] x-apidog-folder: Scraping Browser x-apidog-status: released x-run-in-apidog: https://app.apidog.com/web/project/745098/apis/api-24826702-run components: schemas: {} securitySchemes: bearer: type: bearer scheme: bearer description: Bearer token authentication using your Scrapeless API key apikey-header-x-api-token: type: apiKey in: header name: x-api-token servers: - url: https://api.scrapeless.com description: Prod Env security: - apikey-header-x-api-token: [] ```