> ## Documentation Index > Fetch the complete documentation index at: https://tbd-6fc993ce-hypeship-changelog-august-13.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # List browser pools > List browser pools in the resolved project. ## OpenAPI ````yaml https://api.onkernel.com/spec.json get /browser_pools openapi: 3.1.0 info: description: Developer tools and cloud infrastructure for AI agents to use web browsers title: Kernel API version: 0.1.0 servers: - description: API Server url: https://api.onkernel.com security: - bearerAuth: [] tags: - description: Create and manage browser sessions. name: Browsers - description: Control mouse, keyboard, and screen on the browser instance. name: Browser Computer Controls - description: Execute Playwright code against the browser instance. name: Browser Playwright - description: Read, write, and manage files on the browser instance. name: Browser Filesystem - description: Execute and manage processes on the browser instance. name: Browser Processes - description: Record and manage browser session video replays. name: Browser Replays - description: Stream logs from the browser instance. name: Browser Logs - description: Stream live telemetry events from a browser session. name: Browser Telemetry - description: Create, list, retrieve, and delete browser profiles. name: Profiles - description: Create and manage proxy configurations for routing browser traffic. name: Proxies - description: Create, list, retrieve, and delete browser extensions. name: Extensions - description: Create and manage browser pools for acquiring and releasing browsers. name: Browser Pools - description: Inspect the identity and authorization context for the current request. name: Authentication - description: >- Create and manage auth connections for automated credential capture and login. name: Managed Auth - description: Create and manage credentials for authentication. name: Credentials - description: Configure external credential providers like 1Password. name: Credential Providers - description: List applications and versions. name: Apps - description: Create and manage app deployments and stream deployment events. name: Deployments - description: Invoke actions and stream or query invocation status and events. name: Invocations - description: Read and manage organization-level limits. name: Organization - description: | Create and manage projects for resource isolation within an organization. When projects are disabled for the organization, project operations return `404` with code `projects_disabled`. name: Projects - description: Create and manage API keys for organization and project-scoped access. name: API Keys - description: Read audit log records for the authenticated organization. name: Audit Logs - description: Resolve browser and proxy recommendations for bot-protected sites. name: Site Configs paths: /browser_pools: get: tags: - Browser Pools summary: List browser pools description: List browser pools in the resolved project. operationId: getBrowserPools parameters: - description: Limit the number of browser pools to return. in: query name: limit required: false schema: default: 20 maximum: 100 minimum: 1 type: integer - description: Offset the number of browser pools to return. in: query name: offset required: false schema: default: 0 minimum: 0 type: integer - description: >- Case-insensitive substring match against browser pool name. IDs match by exact value. in: query name: query required: false schema: type: string - description: >- Exact-match filter on browser pool name using the database collation. In production, matching is case- and accent-insensitive. During the default-project migration, unscoped requests prefer a concrete default-project browser pool over a legacy unscoped browser pool with the same name. in: query name: name required: false schema: type: string - description: >- Filter pools by geographic region. Omit to list pools in all regions. in: query name: region required: false schema: $ref: '#/components/schemas/Region' responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/BrowserPool' type: array description: List of browser pools headers: X-Has-More: description: Whether there are more browser pools to fetch. schema: default: false type: boolean X-Limit: description: Limit the number of browser pools to return. schema: default: 20 maximum: 100 minimum: 1 type: integer X-Next-Offset: description: >- The offset where the next page starts. 0 when there are no more results. schema: nullable: true type: integer X-Offset: description: The offset of browser pools to return. schema: default: 0 minimum: 0 type: integer '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalError' security: - bearerAuth: [] components: schemas: Region: description: | Geographic region for hosting browser sessions or pools. enum: - us-east - eu-west type: string BrowserPool: description: A browser pool containing multiple identically configured browsers. properties: acquired_count: description: Number of browsers currently acquired from the pool example: 15 type: integer available_count: description: Number of browsers currently available in the pool example: 85 type: integer browser_pool_config: $ref: '#/components/schemas/BrowserPoolConfig' description: Configuration used to create all browsers in this pool created_at: description: Timestamp when the browser pool was created format: date-time type: string extension_ids: 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 type: array id: description: Unique identifier for the browser pool example: iv25ujqf37x3j07dwoffegqr type: string name: description: Browser pool name, if set example: my-pool type: string profile_id: 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 type: string region: $ref: '#/components/schemas/Region' description: > Geographic region of the browser pool. Fixed once the pool is created. required: - id - available_count - acquired_count - created_at - region - browser_pool_config - extension_ids type: object BrowserPoolConfig: description: | Effective browser pool configuration returned by the API. properties: chrome_policy: 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. type: object extensions: description: >- List of browser extensions to load into the session. Provide each by id or name. items: $ref: '#/components/schemas/BrowserExtension' maxItems: 20 type: array fill_rate_per_minute: 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 type: integer headless: description: If true, launches the browser using a headless image. example: false type: boolean kiosk_mode: description: >- If true, launches the browser in kiosk mode to hide address bar and tabs in live view. example: true type: boolean name: description: >- Optional name for the browser pool. Must be unique within the project. example: my-pool pattern: ^[a-zA-Z0-9._-]{1,255}$ type: string network: $ref: '#/components/schemas/BrowserNetworkConfig' description: >- Network configuration applied to browsers in this pool, if any. Omitted when the pool has no network configuration. profile: allOf: - $ref: '#/components/schemas/BrowserPoolProfile' description: Profile selection for browsers in the pool. proxy_id: description: >- Optional proxy associated to the browser session. References a proxy in the same project as the browser session. type: string refresh_on_profile_update: 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 type: boolean size: 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). example: 10 minimum: 1 type: integer start_url: 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 maxLength: 2048 type: string stealth: description: >- If true, launches the browser in stealth mode to reduce detection by anti-bot mechanisms. example: true type: boolean telemetry: $ref: '#/components/schemas/BrowserTelemetryConfig' description: >- Active telemetry configuration applied to browsers warmed into this pool, if any. nullable: true timeout_seconds: description: >- Default idle timeout in seconds for browsers acquired from this pool before they are destroyed. Minimum 10, maximum 259200 (72 hours). maximum: 259200 minimum: 10 type: integer viewport: allOf: - $ref: '#/components/schemas/BrowserViewport' description: Browser viewport used for newly-warmed browsers in this pool. required: - size type: object Error: properties: code: description: Application-specific error code (machine-readable) example: bad_request type: string details: description: Additional error details (for multiple errors) items: $ref: '#/components/schemas/ErrorDetail' type: array inner_error: $ref: '#/components/schemas/ErrorDetail' message: description: Human-readable error description for debugging example: 'Missing required field: app_name' type: string required: - code - message type: object BrowserExtension: description: > Extension selection for the browser session. Provide either id or name of an extension uploaded to Kernel. oneOf: - required: - id - required: - name properties: id: description: Extension ID to load for this browser session type: string name: description: >- Extension name to load for this browser session (instead of id). Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens. maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9._-]{1,255}$ type: string type: object BrowserNetworkConfig: description: | Network configuration for a browser session or browser pool. properties: private_hosts: description: > Destinations the browser reaches directly through the session's own network instead of through Kernel-managed egress — for private hosts reachable over a VPN or tunnel the session has joined (e.g. a Tailscale tailnet). By default, private IP ranges already route directly: RFC1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), CGNAT/Tailscale (100.64.0.0/10), and IPv6 ULA (fc00::/7). An explicitly supplied list replaces those defaults with exactly the entries given, and an empty list ([]) disables them so all traffic uses Kernel-managed egress; omit private_hosts to keep the defaults. Entries are hostname patterns ("*.example.ts.net", "preview.internal") or IP/CIDR literals ("100.64.0.0/10", "10.1.30.63"). IP and CIDR entries only match URLs written with a literal IP address; they never match hostnames that resolve into the range, so private DNS names need a hostname entry even when they resolve inside the default ranges. CIDRs must be in canonical masked form (host bits zero), and only the private ranges listed above are accepted; public, loopback, link-local, and unspecified ranges are rejected. Exact IPv6 addresses must be bracketed ("[fd00::1]"); IPv6 CIDR ranges are unbracketed ("fd00::/8"). Wildcards are limited to one leading "*." over a suffix with at least two labels that is not a public suffix (so "*.co.uk" or "*.ts.net" are rejected, while "*.example.ts.net" is accepted). Hostname and IP entries may carry a port; CIDR ranges may not. Hostname entries are not resolved during validation, so callers must ensure they identify private destinations. Not related to a proxy's bypass_hosts, which selects between upstream-proxy and Kernel-managed direct egress and cannot reach into a VPN. example: - '*.example.ts.net' - 100.64.0.0/10 items: maxLength: 255 type: string maxItems: 32 type: array type: object BrowserPoolProfile: 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. oneOf: - required: - id - required: - name properties: id: description: Profile ID to load for browsers in this pool type: string name: 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. maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9._-]{1,255}$ type: string type: object BrowserTelemetryConfig: description: Active telemetry configuration for a browser session. properties: browser: $ref: '#/components/schemas/BrowserTelemetryCategoriesConfig' description: Per-category enable/disable flags. export: $ref: '#/components/schemas/BrowserTelemetryExportConfig' description: >- Where the session's captured telemetry is being exported. Omitted when the export state is unknown. type: object BrowserViewport: 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: height: description: Browser window height in pixels. Any positive integer is accepted. example: 800 minimum: 1 type: integer refresh_rate: description: >- Display refresh rate in Hz. Any positive integer is accepted; if omitted, automatically determined from width and height. example: 60 minimum: 1 type: integer width: description: Browser window width in pixels. Any positive integer is accepted. example: 1280 minimum: 1 type: integer required: - width - height type: object ErrorDetail: properties: code: description: Lower-level error code providing more specific detail example: invalid_input type: string message: description: Further detail about the error example: Provided version string is not semver compliant type: string type: object BrowserTelemetryCategoriesConfig: 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: captcha: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: Captcha solve attempt outcomes. On by default. connection: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Client attach/detach lifecycle for the CDP proxy and live view. On by default. console: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Console output (log, warn, error) and uncaught exceptions. 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. 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. page: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Page lifecycle events including navigation, DOMContentLoaded, load, layout shifts, and LCP. CDP category; off by default. screenshot: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Periodic base64-encoded viewport screenshots. High volume; off by default and must be opted into. system: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- Browser VM health, such as out-of-memory kills and managed-service crashes. On by default. type: object BrowserTelemetryExportConfig: description: Active export state for a session's captured telemetry, by protocol. properties: otlp: $ref: '#/components/schemas/BrowserTelemetryOTLPExportConfig' description: Active OTLP export state. type: object BrowserTelemetryCategoryConfig: description: Per-category telemetry configuration. properties: enabled: 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. type: boolean type: object BrowserTelemetryOTLPExportConfig: description: Active OTLP export state for a browser session. properties: destination: description: >- ID of the OTLP destination the session is bound to. Omitted when the session is not exporting. type: string enabled: description: Whether the session is exporting captured telemetry over OTLP. type: boolean type: object responses: BadRequest: content: application/json: schema: $ref: '#/components/schemas/Error' description: Bad Request – invalid input Unauthorized: content: application/json: schema: $ref: '#/components/schemas/Error' description: Unauthorized – missing or invalid authorization token Forbidden: content: application/json: schema: $ref: '#/components/schemas/Error' description: Forbidden – insufficient permissions or plan InternalError: content: application/json: schema: $ref: '#/components/schemas/Error' description: Internal Server Error securitySchemes: bearerAuth: scheme: bearer type: http ````