> ## Documentation Index > Fetch the complete documentation index at: https://tbd-6fc993ce-hypeship-document-audit-logs-api.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create a browser pool > 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. ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/kernel/openapi.documented.yml post /browser_pools openapi: 3.1.0 info: title: Kernel API description: Developer tools and cloud infrastructure for AI agents to use web browsers version: 0.1.0 servers: - url: https://api.onkernel.com description: API Server security: - bearerAuth: [] tags: - name: Browsers description: Create and manage browser sessions. - name: Browser Computer Controls description: Control mouse, keyboard, and screen on the browser instance. - name: Browser Playwright description: Execute Playwright code against the browser instance. - name: Browser Filesystem description: Read, write, and manage files on the browser instance. - name: Browser Processes description: Execute and manage processes on the browser instance. - name: Browser Replays description: Record and manage browser session video replays. - name: Browser Logs description: Stream logs from the browser instance. - name: Browser Telemetry description: Stream live telemetry events from a browser session. - name: Profiles description: Create, list, retrieve, and delete browser profiles. - name: Proxies description: Create and manage proxy configurations for routing browser traffic. - name: Extensions description: Create, list, retrieve, and delete browser extensions. - name: Browser Pools description: Create and manage browser pools for acquiring and releasing browsers. - name: Managed Auth description: >- Create and manage auth connections for automated credential capture and login. - name: Credentials description: Create and manage credentials for authentication. - name: Credential Providers description: Configure external credential providers like 1Password. - name: Apps description: List applications and versions. - name: Deployments description: Create and manage app deployments and stream deployment events. - name: Invocations description: Invoke actions and stream or query invocation status and events. - name: Organization description: Read and manage organization-level limits. - name: Projects description: Create and manage projects for resource isolation within an organization. - name: API Keys description: Create and manage API keys for organization and project-scoped access. - name: Audit Logs description: Read audit log records for the authenticated organization. paths: /browser_pools: post: tags: - Browser Pools summary: Create a browser pool description: > 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. operationId: postBrowserPools requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BrowserPoolCreateRequest' responses: '201': description: Browser pool created successfully content: application/json: schema: $ref: '#/components/schemas/BrowserPool' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' security: - bearerAuth: [] x-codeSamples: - lang: JavaScript source: |- 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); - lang: Python source: |- 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) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tbrowserPool, err := client.BrowserPools.New(context.TODO(), kernel.BrowserPoolNewParams{\n\t\tSize: 10,\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", browserPool.ID)\n}\n" components: schemas: BrowserPoolCreateRequest: type: object description: > Parameters for creating a browser pool. All browsers in the pool will be created with the same configuration. properties: size: type: integer description: > 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). minimum: 1 example: 10 name: type: string pattern: ^[a-zA-Z0-9._-]{1,255}$ description: >- Optional name for the browser pool. Must be unique within the project. example: my-pool fill_rate_per_minute: type: integer description: >- 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. minimum: 0 default: 25 timeout_seconds: type: integer description: >- 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). minimum: 10 maximum: 259200 default: 600 stealth: type: boolean description: >- If true, launches the browser in stealth mode to reduce detection by anti-bot mechanisms. Defaults to false. default: false example: true headless: type: boolean description: >- If true, launches the browser using a headless image. Defaults to false. default: false example: false profile: allOf: - $ref: '#/components/schemas/BrowserPoolProfile' description: Profile selection for browsers in the pool. refresh_on_profile_update: type: boolean description: > 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. example: true default: false extensions: type: array description: >- List of browser extensions to load into the session. Provide each by id or name. maxItems: 20 items: $ref: '#/components/schemas/BrowserExtension' proxy_id: type: string description: >- Optional proxy to associate to the browser session. Must reference a proxy in the same project as the browser session. viewport: allOf: - $ref: '#/components/schemas/BrowserViewport' description: Browser viewport used for newly-warmed browsers in this pool. kiosk_mode: type: boolean description: >- If true, launches the browser in kiosk mode to hide address bar and tabs in live view. Defaults to false. default: false example: true chrome_policy: type: object additionalProperties: true description: > 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: type: string maxLength: 2048 description: > 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. example: https://example.com telemetry: $ref: '#/components/schemas/BrowserTelemetryRequestConfig' nullable: true description: > Telemetry configuration applied to browsers warmed into this pool. Set enabled to true to start capture using the default set, or provide browser category settings. If omitted, null, set to an empty object ({}), set to enabled: false without browser category settings, or all four CDP categories are explicitly disabled, no telemetry is configured on the pool. Only applied to newly-warmed browsers. required: - size BrowserPool: type: object description: A browser pool containing multiple identically configured browsers. properties: id: type: string description: Unique identifier for the browser pool example: iv25ujqf37x3j07dwoffegqr name: type: string description: Browser pool name, if set example: my-pool available_count: type: integer description: Number of browsers currently available in the pool example: 85 acquired_count: type: integer description: Number of browsers currently acquired from the pool example: 15 created_at: type: string format: date-time description: Timestamp when the browser pool was created browser_pool_config: $ref: '#/components/schemas/BrowserPoolConfig' description: Configuration used to create all browsers in this pool profile_id: type: string description: >- 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 extension_ids: type: array description: >- 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). items: type: string required: - id - available_count - acquired_count - created_at - browser_pool_config - extension_ids BrowserPoolProfile: type: object description: > 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. properties: id: type: string description: Profile ID to load for browsers in this pool name: type: string minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9._-]{1,255}$ description: >- Profile name to load for browsers in this pool (instead of id). Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens. oneOf: - required: - id - required: - name BrowserExtension: type: object description: > Extension selection for the browser session. Provide either id or name of an extension uploaded to Kernel. properties: id: type: string description: Extension ID to load for this browser session name: type: string minLength: 1 maxLength: 255 pattern: ^[a-zA-Z0-9._-]{1,255}$ description: >- Extension name to load for this browser session (instead of id). Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens. oneOf: - required: - id - required: - name BrowserViewport: type: object description: > 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). properties: width: type: integer description: Browser window width in pixels. Any positive integer is accepted. minimum: 1 example: 1280 height: type: integer description: Browser window height in pixels. Any positive integer is accepted. minimum: 1 example: 800 refresh_rate: type: integer description: >- Display refresh rate in Hz. Any positive integer is accepted; if omitted, automatically determined from width and height. minimum: 1 example: 60 required: - width - height BrowserTelemetryRequestConfig: type: object description: Telemetry request configuration for a browser session. properties: enabled: type: boolean description: >- 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: $ref: '#/components/schemas/BrowserTelemetryCategoriesConfig' description: >- Per-category capture flags. The operational categories (control, connection, system, captcha) are captured whenever telemetry is enabled; set one to enabled=false to opt out. The CDP categories (console, network, page, interaction) and screenshot are off by default; set enabled=true to opt in. On create, provided categories layer onto the default set. On update, provided categories merge onto the session's current config; when no telemetry is active this falls back to the default set (matching create). If browser is omitted or empty, the default set is used. A browser config that disables every category stops capture on update and starts no capture on create. BrowserPoolConfig: type: object description: | Effective browser pool configuration returned by the API. properties: size: type: integer description: > 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). minimum: 1 example: 10 name: type: string pattern: ^[a-zA-Z0-9._-]{1,255}$ description: >- Optional name for the browser pool. Must be unique within the project. example: my-pool fill_rate_per_minute: type: integer description: >- 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. minimum: 0 timeout_seconds: type: integer description: >- Default idle timeout in seconds for browsers acquired from this pool before they are destroyed. Minimum 10, maximum 259200 (72 hours). minimum: 10 maximum: 259200 stealth: type: boolean description: >- If true, launches the browser in stealth mode to reduce detection by anti-bot mechanisms. example: true headless: type: boolean description: If true, launches the browser using a headless image. example: false profile: allOf: - $ref: '#/components/schemas/BrowserPoolProfile' description: Profile selection for browsers in the pool. refresh_on_profile_update: type: boolean description: > 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. example: true extensions: type: array description: >- List of browser extensions to load into the session. Provide each by id or name. maxItems: 20 items: $ref: '#/components/schemas/BrowserExtension' proxy_id: type: string description: >- Optional proxy associated to the browser session. References a proxy in the same project as the browser session. viewport: allOf: - $ref: '#/components/schemas/BrowserViewport' description: Browser viewport used for newly-warmed browsers in this pool. kiosk_mode: type: boolean description: >- If true, launches the browser in kiosk mode to hide address bar and tabs in live view. example: true chrome_policy: type: object additionalProperties: true description: > 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: type: string maxLength: 2048 description: > 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. example: https://example.com telemetry: $ref: '#/components/schemas/BrowserTelemetryConfig' nullable: true description: >- Active telemetry configuration applied to browsers warmed into this pool, if any. required: - size Error: type: object required: - code - message properties: code: type: string description: Application-specific error code (machine-readable) example: bad_request message: type: string description: Human-readable error description for debugging example: 'Missing required field: app_name' details: type: array description: Additional error details (for multiple errors) items: $ref: '#/components/schemas/ErrorDetail' inner_error: $ref: '#/components/schemas/ErrorDetail' BrowserTelemetryCategoriesConfig: type: object description: >- 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. properties: console: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Console output (log, warn, error) and uncaught exceptions. CDP category; off by default. page: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Page lifecycle events including navigation, DOMContentLoaded, load, layout shifts, and LCP. CDP category; off by default. interaction: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- User interaction events including clicks, keydowns, and scroll-settled events. CDP category; off by default. network: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- HTTP request and response metadata including URL, method, status code, and timing. Request post data is forwarded as-is from CDP. Text response bodies are truncated at 8 KB for structured types (JSON, XML, form data) and 4 KB for other text types. Binary responses (images, fonts, media) are excluded. CDP category; off by default. control: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Agent-driven actions against the browser, such as inbound calls to the in-VM API. On by default. connection: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Client attach/detach lifecycle for the CDP proxy and live view. On by default. system: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Browser VM health, such as out-of-memory kills and managed-service crashes. On by default. screenshot: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Periodic base64-encoded viewport screenshots. High volume; off by default and must be opted into. captcha: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: Captcha solve attempt outcomes. On by default. BrowserTelemetryConfig: type: object description: Active telemetry configuration for a browser session. properties: browser: $ref: '#/components/schemas/BrowserTelemetryCategoriesConfig' description: Per-category enable/disable flags. ErrorDetail: type: object properties: code: type: string description: Lower-level error code providing more specific detail example: invalid_input message: type: string description: Further detail about the error example: Provided version string is not semver compliant BrowserTelemetryCategoryConfig: type: object description: Per-category telemetry configuration. properties: enabled: type: boolean description: >- 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. responses: BadRequest: description: Bad Request – invalid input content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized – missing or invalid authorization token content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Forbidden – insufficient permissions or plan content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: Conflict – resource already exists content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: Too Many Requests – rate limit exceeded headers: Retry-After: description: Seconds to wait before retrying schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' InternalError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer ````