Skip to main content
POST
/
browser_pools
JavaScript
import Kernel from '@onkernel/sdk';

const client = new Kernel({
  apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted
});

const browserPool = await client.browserPools.create({ size: 10 });

console.log(browserPool.id);
import os
from kernel import Kernel

client = Kernel(
    api_key=os.environ.get("KERNEL_API_KEY"),  # This is the default and can be omitted
)
browser_pool = client.browser_pools.create(
    size=10,
)
print(browser_pool.id)
package main

import (
	"context"
	"fmt"

	"github.com/kernel/kernel-go-sdk"
	"github.com/kernel/kernel-go-sdk/option"
)

func main() {
	client := kernel.NewClient(
		option.WithAPIKey("My API Key"),
	)
	browserPool, err := client.BrowserPools.New(context.TODO(), kernel.BrowserPoolNewParams{
		Size: 10,
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", browserPool.ID)
}
curl --request POST \
  --url https://api.onkernel.com/browser_pools \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "size": 10,
  "name": "my-pool",
  "fill_rate_per_minute": 10,
  "timeout_seconds": 600,
  "stealth": true,
  "headless": false,
  "profile": {
    "id": "<string>",
    "name": "<string>"
  },
  "refresh_on_profile_update": true,
  "extensions": [
    {
      "id": "<string>",
      "name": "<string>"
    }
  ],
  "proxy_id": "<string>",
  "kiosk_mode": true,
  "chrome_policy": {},
  "start_url": "https://example.com"
}
'
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.onkernel.com/browser_pools",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'size' => 10,
    'name' => 'my-pool',
    'fill_rate_per_minute' => 10,
    'timeout_seconds' => 600,
    'stealth' => true,
    'headless' => false,
    'profile' => [
        'id' => '<string>',
        'name' => '<string>'
    ],
    'refresh_on_profile_update' => true,
    'extensions' => [
        [
                'id' => '<string>',
                'name' => '<string>'
        ]
    ],
    'proxy_id' => '<string>',
    'kiosk_mode' => true,
    'chrome_policy' => [
        
    ],
    'start_url' => 'https://example.com'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
HttpResponse<String> response = Unirest.post("https://api.onkernel.com/browser_pools")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"size\": 10,\n  \"name\": \"my-pool\",\n  \"fill_rate_per_minute\": 10,\n  \"timeout_seconds\": 600,\n  \"stealth\": true,\n  \"headless\": false,\n  \"profile\": {\n    \"id\": \"<string>\",\n    \"name\": \"<string>\"\n  },\n  \"refresh_on_profile_update\": true,\n  \"extensions\": [\n    {\n      \"id\": \"<string>\",\n      \"name\": \"<string>\"\n    }\n  ],\n  \"proxy_id\": \"<string>\",\n  \"kiosk_mode\": true,\n  \"chrome_policy\": {},\n  \"start_url\": \"https://example.com\"\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.onkernel.com/browser_pools")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"size\": 10,\n  \"name\": \"my-pool\",\n  \"fill_rate_per_minute\": 10,\n  \"timeout_seconds\": 600,\n  \"stealth\": true,\n  \"headless\": false,\n  \"profile\": {\n    \"id\": \"<string>\",\n    \"name\": \"<string>\"\n  },\n  \"refresh_on_profile_update\": true,\n  \"extensions\": [\n    {\n      \"id\": \"<string>\",\n      \"name\": \"<string>\"\n    }\n  ],\n  \"proxy_id\": \"<string>\",\n  \"kiosk_mode\": true,\n  \"chrome_policy\": {},\n  \"start_url\": \"https://example.com\"\n}"

response = http.request(request)
puts response.read_body
{
  "id": "iv25ujqf37x3j07dwoffegqr",
  "available_count": 85,
  "acquired_count": 15,
  "created_at": "2023-11-07T05:31:56Z",
  "browser_pool_config": {
    "size": 10,
    "name": "my-pool",
    "fill_rate_per_minute": 1,
    "timeout_seconds": 129605,
    "stealth": true,
    "headless": false,
    "profile": {
      "id": "<string>",
      "name": "<string>"
    },
    "refresh_on_profile_update": true,
    "extensions": [
      {
        "id": "<string>",
        "name": "<string>"
      }
    ],
    "proxy_id": "<string>",
    "viewport": {
      "width": 1280,
      "height": 800,
      "refresh_rate": 60
    },
    "kiosk_mode": true,
    "chrome_policy": {},
    "start_url": "https://example.com"
  },
  "extension_ids": [
    "<string>"
  ],
  "name": "my-pool",
  "profile_id": "iv25ujqf37x3j07dwoffegqr"
}
{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}
{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}
{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}
{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}
{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}
{
  "code": "bad_request",
  "message": "Missing required field: app_name",
  "details": [
    {
      "code": "invalid_input",
      "message": "Provided version string is not semver compliant"
    }
  ],
  "inner_error": {
    "code": "invalid_input",
    "message": "Provided version string is not semver compliant"
  }
}

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 maintain in the pool. The maximum size is determined by your organization's pooled sessions limit (the sum of all pool sizes cannot exceed your limit).

Required range: x >= 1
Example:

10

​
name
string

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

Pattern: ^[a-zA-Z0-9._-]{1,255}$
Example:

"my-pool"

​
fill_rate_per_minute
integer
default:10

Percentage of the pool to fill per minute. Defaults to 10. The cap is 25 for most organizations but can be raised per-organization, so only the lower bound is enforced here.

Required range: x >= 0
​
timeout_seconds
integer
default:600

Default idle timeout in seconds for browsers acquired from this pool before they are destroyed. Defaults to 600 seconds. Minimum 10, maximum 259200 (72 hours).

Required range: 10 <= x <= 259200
​
stealth
boolean
default:false

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

Example:

true

​
headless
boolean
default:false

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

Example:

false

​
profile
object

Profile selection for browsers in the pool.

​
refresh_on_profile_update
boolean
default:false

When true, flush idle browsers when the profile the pool uses is updated, so pool browsers pick up the latest profile data. Requires a profile to be set on the pool.

Example:

true

​
extensions
object[]

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

Maximum array length: 20

Extension selection for the browser session. Provide either id or name of an extension uploaded to Kernel.

​
proxy_id
string

Optional proxy to associate to the browser session. Must reference a proxy in the same project as the browser session.

​
viewport
object

Browser viewport used for newly-warmed browsers in this pool.

​
kiosk_mode
boolean
default:false

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

Example:

true

​
chrome_policy
object

Custom Chrome enterprise policy overrides applied to all browsers in this pool. Keys are Chrome enterprise policy names; values must match their expected types. Blocked: kernel-managed policies (extensions, proxy, CDP/automation). See https://chromeenterprise.google/policies/ The serialized JSON payload is capped at 5 MiB.

​
start_url
string

Optional URL to navigate to when a new browser is warmed into the pool. Best-effort: failures to navigate do not fail pool fill. Only applied to newly-warmed browsers; browsers reused via release/acquire keep whatever URL the previous lease left them on. Accepts any URL Chromium can resolve, including chrome:// pages.

Maximum string length: 2048
Example:

"https://example.com"

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

​
extension_ids
string[]
required

Resolved extension IDs attached to the pool, in configured load order. Empty when no extensions are attached. Authoritative for programmatic consumers; the extensions inside browser_pool_config reflect the configured selector (echoed as sent on create).

​
name
string

Browser pool name, if set

Example:

"my-pool"

​
profile_id
string

Resolved profile ID the pool is attached to. Omitted when no profile is attached. Authoritative for programmatic consumers; the profile inside browser_pool_config reflects the configured selector (echoed as sent on create).

Example:

"iv25ujqf37x3j07dwoffegqr"