ONonkernel
Browser Pools

Update a browser pool

Changed on

Updates the configuration used to create browsers in the pool. As with creation, save_changes on the pool profile is ignored (not rejected); pooled browsers never persist changes back to the profile. To clear the profile reference, send profile: { "id": "" }. Clearing the profile also disables refresh_on_profile_update.

patch/browser_pools/{id_or_name}

Request

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

Path parameters

id_or_namestring required

Browser pool ID or name

Request body

chrome_policyobject

If provided, replaces the custom Chrome enterprise policy overrides applied to all browsers in this pool. Empty object clears any previously-set policy. 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.

discard_all_idleboolean

Whether to discard all idle browsers and rebuild them immediately with the new configuration. Defaults to false. Only browsers that are idle when the update runs are rebuilt. A browser that is in use during the update keeps its original configuration, except that its allowlist is reset to the current pool baseline on release or the browser is replaced. For other configuration fields, if it is later released with reuse: true it returns to the pool with that stale configuration until it is discarded (by this flag on a later update, or by flushing the pool).

fill_rate_per_minuteinteger

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

headlessboolean

If provided, replaces whether browsers launch using a headless image.

kiosk_modeboolean

If provided, replaces whether browsers launch in kiosk mode.

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

Memory requested for newly-warmed browsers in this pool: 1GiB, 2GiB, or 4GiB for headless, 8GiB or 16GiB for headful. Existing browsers retain their original allocation. Use discard_all_idle to replace idle browsers.

namestring

If provided, replaces the pool name. Empty string is a no-op; the pool name cannot be cleared or reset to empty once assigned.

proxy_idstring

Empty string clears the previously-selected proxy. Omit this field to leave the proxy unchanged.

refresh_on_profile_updateboolean

If provided, replaces whether idle browsers are flushed when the profile the pool uses is updated. When the pool's profile reference is changed (including newly attached) and this field is omitted, it defaults to true. Re-sending the same profile reference leaves this setting unchanged. Clearing the profile also disables this setting. Requires a profile to be set on the pool.

sizeinteger

If provided, replaces the 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

If provided, replaces the URL to navigate to when a new browser is warmed into the pool. Empty string clears the previously-set URL. Omit this field to leave it unchanged.

stealthboolean

If provided, replaces whether browsers launch in stealth mode.

timeout_secondsinteger

If provided, replaces the default idle timeout in seconds for browsers acquired from this pool before they are destroyed. Minimum 10, maximum 259200 (72 hours).

Example request

{
  "expected_network": {
    "allowed_hosts": [
      "example.com",
      "*.example.com"
    ],
    "private_hosts": [
      "*.example.ts.net",
      "100.64.0.0/10"
    ]
  },
  "kiosk_mode": true,
  "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 details

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

      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