ONonkernel
Browser Pools

Create a browser pool

Changed on

Create a new browser pool with the specified configuration and size. Pooled browsers load their profile read-only: any save_changes on the profile is ignored (not rejected), so pooled browsers never persist changes back to the profile.

post/browser_pools

Request

  • Base URL
    https://api.onkernel.com
  • URL
    https://api.onkernel.com/browser_pools
  • Auth
    HTTP bearer

Request body

chrome_policyobject

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.

fill_rate_per_minuteinteger

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

headlessboolean

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

kiosk_modeboolean

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

memory'1GiB' | '2GiB' | '4GiB' | '8GiB' | '16GiB'

Memory requested for a non-GPU browser. Headless browsers support 1GiB (default), 2GiB, or 4GiB; headful browsers support 8GiB (default) or 16GiB.

namestring

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

proxy_idstring

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

refresh_on_profile_updateboolean

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

region'us-east' | 'us-west' | 'eu-west' | 'ap-southeast'

Geographic region for hosting browser sessions or pools.

sizeinteger 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).

start_urlstring

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.

stealthboolean

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

timeout_secondsinteger

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).

Example request

{
  "kiosk_mode": true,
  "memory": "8GiB",
  "name": "my-pool",
  "network": {
    "allowed_hosts": [
      "example.com",
      "*.example.com"
    ],
    "private_hosts": [
      "*.example.ts.net",
      "100.64.0.0/10"
    ]
  },
  "refresh_on_profile_update": true,
  "size": 10,
  "start_url": "https://example.com",
  "stealth": true,
  "viewport": {
    "height": 800,
    "refresh_rate": 60,
    "width": 1280
  }
}

Response

Browser pool created successfully

acquired_countinteger required

Number of browsers currently acquired from the pool

available_countinteger required

Number of browsers currently available in the pool

created_atstring date-time required

Timestamp when the browser pool was created

extension_idsstring[] 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).

idstring required

Unique identifier for the browser pool

namestring

Browser pool name, if set

profile_idstring

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).

region'us-east' | 'us-west' | 'eu-west' | 'ap-southeast' required

Geographic region for hosting browser sessions or pools.

Example response

{
  "acquired_count": 15,
  "available_count": 85,
  "browser_pool_config": {
    "kiosk_mode": true,
    "memory": "8GiB",
    "name": "my-pool",
    "network": {
      "allowed_hosts": [
        "example.com",
        "*.example.com"
      ],
      "private_hosts": [
        "*.example.ts.net",
        "100.64.0.0/10"
      ]
    },
    "refresh_on_profile_update": true,
    "size": 10,
    "start_url": "https://example.com",
    "stealth": true,
    "viewport": {
      "height": 800,
      "refresh_rate": 60,
      "width": 1280
    }
  },
  "id": "iv25ujqf37x3j07dwoffegqr",
  "name": "my-pool",
  "profile_id": "iv25ujqf37x3j07dwoffegqr"
}

Changes

  • df28b52a4950Revision changes
    • info

      added the optional property // to the response with the status

  • 90be865f0e7cRevision changes
    • warning

      added the new 4GiB enum value to the ///// response property for the response status

    • info

      the request property default value 8GiB was removed

    • info

      added the new 1GiB enum value to the request property

    • info

      added the new 2GiB enum value to the request property

    • info

      added the new 4GiB enum value to the request property