Skip to main content
POST
/
browser_pools
Create a browser pool
curl --request POST \
  --url https://api.onkernel.com/browser_pools \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "my-pool",
  "size": 10,
  "fill_rate_per_minute": 10,
  "timeout_seconds": 600,
  "stealth": true,
  "headless": false,
  "profile": {
    "id": "<string>",
    "name": "<string>",
    "save_changes": false
  },
  "extensions": [
    {
      "id": "<string>",
      "name": "<string>"
    }
  ],
  "proxy_id": "<string>",
  "viewport": {
    "width": 1280,
    "height": 800,
    "refresh_rate": 60
  },
  "kiosk_mode": true
}'
{
  "id": "iv25ujqf37x3j07dwoffegqr",
  "name": "my-pool",
  "available_count": 85,
  "acquired_count": 15,
  "created_at": "2023-11-07T05:31:56Z",
  "browser_pool_config": {
    "name": "my-pool",
    "size": 10,
    "fill_rate_per_minute": 10,
    "timeout_seconds": 600,
    "stealth": true,
    "headless": false,
    "profile": {
      "id": "<string>",
      "name": "<string>",
      "save_changes": false
    },
    "extensions": [
      {
        "id": "<string>",
        "name": "<string>"
      }
    ],
    "proxy_id": "<string>",
    "viewport": {
      "width": 1280,
      "height": 800,
      "refresh_rate": 60
    },
    "kiosk_mode": true
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Parameters for creating a browser pool. All browsers in the pool will be created with the same configuration.

​
size
integer
required

Number of browsers to create in the pool

Required range: 1 <= x <= 50
Example:

10

​
name
string

Optional name for the browser pool. Must be unique within the organization.

Example:

"my-pool"

​
fill_rate_per_minute
integer
default:10

Percentage of the pool to fill per minute. Defaults to 10%.

Required range: 0 <= x <= 25
​
timeout_seconds
integer
default:600

Default idle timeout in seconds for browsers acquired from this pool before they are destroyed. Defaults to 600 seconds if not specified

Required range: 60 <= x <= 86400
​
stealth
boolean

If true, launches the browser in stealth mode to reduce detection by anti-bot mechanisms.

Example:

true

​
headless
boolean

If true, launches the browser using a headless image. Defaults to false.

Example:

false

​
profile
object

Profile selection for the browser session. Provide either id or name. If specified, the matching profile will be loaded into the browser session. Profiles must be created beforehand.

  • Option 1
  • Option 2
​
extensions
object[]

List of browser extensions to load into the session. Provide each by id or name.

Maximum length: 20
  • Option 1
  • Option 2
​
proxy_id
string

Optional proxy to associate to the browser session. Must reference a proxy belonging to the caller's org.

​
viewport
object

Initial browser window size in pixels with optional refresh rate. If omitted, image defaults apply (commonly 1024x768@60). Only specific viewport configurations are supported. The server will reject unsupported combinations. Supported resolutions are: 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1024x768@60, 1200x800@60 If refresh_rate is not provided, it will be automatically determined from the width and height if they match a supported configuration exactly. Note: Higher resolutions may affect the responsiveness of live view browser

​
kiosk_mode
boolean

If true, launches the browser in kiosk mode to hide address bar and tabs in live view.

Example:

true

Response

Browser pool created successfully

A browser pool containing multiple identically configured browsers.

​
id
string
required

Unique identifier for the browser pool

Example:

"iv25ujqf37x3j07dwoffegqr"

​
available_count
integer
required

Number of browsers currently available in the pool

Example:

85

​
acquired_count
integer
required

Number of browsers currently acquired from the pool

Example:

15

​
created_at
string<date-time>
required

Timestamp when the browser pool was created

​
browser_pool_config
object
required

Configuration used to create all browsers in this pool

​
name
string

Browser pool name, if set

Example:

"my-pool"