---
title: "Create a browser pool"
method: POST
path: "/browser_pools"
tags: ["Browser Pools"]
---

# Create a browser pool

`POST /browser_pools`

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.

## Request body

- BrowserPoolCreateRequest — 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).
  - `name` string — Optional name for the browser pool. Must be unique within the project.
  - `fill_rate_per_minute` integer — 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.
  - `timeout_seconds` integer — 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).
  - `stealth` boolean — If true, launches the browser in stealth mode to reduce detection by anti-bot mechanisms. Defaults to false.
  - `headless` boolean — If true, launches the browser using a headless image. Defaults to false.
  - `profile` union — Profile configuration for browsers in a pool. Provide either id or name. Profiles must be created beforehand. Unlike single browser sessions, pools load the profile read-only and never persist changes back to it, so save_changes is omitted here. Any save_changes value sent on a pool profile is silently ignored rather than rejected.
    - object
      - `id` string, required — Profile ID to load for browsers in this pool
      - `name` string — Profile name to load for browsers in this pool (instead of id). Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens.
    - object
      - `id` string — Profile ID to load for browsers in this pool
      - `name` string, required — Profile name to load for browsers in this pool (instead of id). Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens.
  - `refresh_on_profile_update` boolean — 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.
  - `extensions` BrowserExtension[] — List of browser extensions to load into the session. Provide each by id or name.
    - union — Extension selection for the browser session. Provide either id or name of an extension uploaded to Kernel.
      - object
        - `id` string, required — Extension ID to load for this browser session
        - `name` string — Extension name to load for this browser session (instead of id). Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens.
      - object
        - `id` string — Extension ID to load for this browser session
        - `name` string, required — Extension name to load for this browser session (instead of id). Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens.
  - `proxy_id` string — Optional proxy to associate to the browser session. Must reference a proxy in the same project as the browser session.
  - `viewport` BrowserViewport — Initial browser window size in pixels with optional refresh rate. If omitted, image defaults apply (1920x1080@25). For GPU images, the default is 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60, 768x1024@60, 390x844@60. For GPU images, recommended presets use one of these resolutions with refresh rates 60, 30, 25, or 10: 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. Viewports outside this list may exhibit unstable live view or recording behavior. If refresh_rate is not provided, it will be automatically determined based on the resolution (higher resolutions use lower refresh rates to keep bandwidth reasonable).
    - `width` integer, required — Browser window width in pixels. Any positive integer is accepted.
    - `height` integer, required — Browser window height in pixels. Any positive integer is accepted.
    - `refresh_rate` integer — Display refresh rate in Hz. Any positive integer is accepted; if omitted, automatically determined from width and height.
  - `kiosk_mode` boolean — If true, launches the browser in kiosk mode to hide address bar and tabs in live view. Defaults to false.
  - `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.
  - `telemetry` BrowserTelemetryRequestConfig — Telemetry request configuration for a browser session.
    - `enabled` boolean — Request shortcut for browser telemetry capture. True enables capture; with no browser category settings it captures the default set (control, connection, system, captcha), and any browser category settings are layered onto that default set. On update, enabled=true resolves the config fresh from the default set plus any provided categories, replacing the session's current selection rather than merging onto it; omit enabled to merge categories onto the current selection instead. False stops capture on update and starts no capture on create. enabled=false cannot be combined with browser category settings.
    - `browser` BrowserTelemetryCategoriesConfig — Per-category telemetry capture settings layered onto the default set. The operational signals (control, connection, system, captcha) are on by default and are opt-out: set one to enabled=false to stop capturing it. The CDP categories (console, network, page, interaction) and screenshot are off by default and are opt-in: set enabled=true to capture them.
      - `console` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `page` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `interaction` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `network` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `control` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `connection` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `system` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `screenshot` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
      - `captcha` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
        - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.

## Response `201`

Browser pool created successfully

- BrowserPool — A browser pool containing multiple identically configured browsers.
  - `id` string, required — Unique identifier for the browser pool
  - `name` string — Browser pool name, if set
  - `available_count` integer, required — Number of browsers currently available in the pool
  - `acquired_count` integer, required — Number of browsers currently acquired from the pool
  - `created_at` string, date-time, required — Timestamp when the browser pool was created
  - `browser_pool_config` BrowserPoolConfig, required — Effective browser pool configuration returned by the API.
    - `size` integer, required — Number of browsers maintained 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).
    - `name` string — Optional name for the browser pool. Must be unique within the project.
    - `fill_rate_per_minute` integer — 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.
    - `timeout_seconds` integer — Default idle timeout in seconds for browsers acquired from this pool before they are destroyed. Minimum 10, maximum 259200 (72 hours).
    - `stealth` boolean — If true, launches the browser in stealth mode to reduce detection by anti-bot mechanisms.
    - `headless` boolean — If true, launches the browser using a headless image.
    - `profile` union — Profile configuration for browsers in a pool. Provide either id or name. Profiles must be created beforehand. Unlike single browser sessions, pools load the profile read-only and never persist changes back to it, so save_changes is omitted here. Any save_changes value sent on a pool profile is silently ignored rather than rejected.
      - object
        - `id` string, required — Profile ID to load for browsers in this pool
        - `name` string — Profile name to load for browsers in this pool (instead of id). Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens.
      - object
        - `id` string — Profile ID to load for browsers in this pool
        - `name` string, required — Profile name to load for browsers in this pool (instead of id). Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens.
    - `refresh_on_profile_update` boolean — 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.
    - `extensions` BrowserExtension[] — List of browser extensions to load into the session. Provide each by id or name.
      - union — Extension selection for the browser session. Provide either id or name of an extension uploaded to Kernel.
        - object
          - `id` string, required — Extension ID to load for this browser session
          - `name` string — Extension name to load for this browser session (instead of id). Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens.
        - object
          - `id` string — Extension ID to load for this browser session
          - `name` string, required — Extension name to load for this browser session (instead of id). Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens.
    - `proxy_id` string — Optional proxy associated to the browser session. References a proxy in the same project as the browser session.
    - `viewport` BrowserViewport — Initial browser window size in pixels with optional refresh rate. If omitted, image defaults apply (1920x1080@25). For GPU images, the default is 1920x1080@60. Arbitrary viewport dimensions and refresh rates are accepted. Known-good presets include: 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60, 768x1024@60, 390x844@60. For GPU images, recommended presets use one of these resolutions with refresh rates 60, 30, 25, or 10: 800x600, 960x720, 1024x576, 1024x768, 1152x648, 1200x800, 1280x720, 1368x768, 1440x900, 1600x900, 1920x1080, 1920x1200, 390x844, 360x250, 768x1024, 800x1600. Viewports outside this list may exhibit unstable live view or recording behavior. If refresh_rate is not provided, it will be automatically determined based on the resolution (higher resolutions use lower refresh rates to keep bandwidth reasonable).
      - `width` integer, required — Browser window width in pixels. Any positive integer is accepted.
      - `height` integer, required — Browser window height in pixels. Any positive integer is accepted.
      - `refresh_rate` integer — Display refresh rate in Hz. Any positive integer is accepted; if omitted, automatically determined from width and height.
    - `kiosk_mode` boolean — If true, launches the browser in kiosk mode to hide address bar and tabs in live view.
    - `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.
    - `telemetry` BrowserTelemetryConfig — Active telemetry configuration for a browser session.
      - `browser` BrowserTelemetryCategoriesConfig — Per-category telemetry capture settings layered onto the default set. The operational signals (control, connection, system, captcha) are on by default and are opt-out: set one to enabled=false to stop capturing it. The CDP categories (console, network, page, interaction) and screenshot are off by default and are opt-in: set enabled=true to capture them.
        - `console` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
          - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
        - `page` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
          - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
        - `interaction` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
          - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
        - `network` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
          - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
        - `control` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
          - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
        - `connection` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
          - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
        - `system` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
          - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
        - `screenshot` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
          - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
        - `captcha` BrowserTelemetryCategoryConfig — Per-category telemetry configuration.
          - `enabled` boolean — Whether this category is captured. Operational categories (control, connection, system, captcha) default to true; set false to opt out. CDP categories (console, network, page, interaction) and screenshot default to false; set true to opt in.
  - `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).
  - `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).

## Other responses

- `400` — Bad Request – invalid input
- `401` — Unauthorized – missing or invalid authorization token
- `403` — Forbidden – insufficient permissions or plan
- `409` — Conflict – resource already exists
- `429` — Too Many Requests – rate limit exceeded
- `500` — Internal Server Error

---

[API](https://skmtc.net/kernel/apis/kernel-api.md) · [All operations](https://skmtc.net/kernel/apis/kernel-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kernel/kernel-api/versions/9e8ce9fcf5e1/schema)