> ## Documentation Index > Fetch the complete documentation index at: https://tbd-6fc993ce-hypeship-ia-how-it-works.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Get browser pool details > Retrieve details for a single browser pool by its ID or name. ## OpenAPI ````yaml https://api.onkernel.com/spec.json get /browser_pools/{id_or_name} 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: Search the web and retrieve content for selected results. name: Search - 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 and manage the executors it runs in. name: Browser Playwright - description: Execute JavaScript in the browser instance's persistent Browser REPL. name: Browser REPL - description: Discover and invoke native page tools across the browser instance. name: Browser WebMCP - 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, and manage the destinations sessions export them to. 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: Config Registry paths: /browser_pools/{id_or_name}: get: tags: - Browser Pools summary: Get browser pool details description: Retrieve details for a single browser pool by its ID or name. operationId: getBrowserPoolsByIdOrName parameters: - description: Browser pool ID or name in: path name: id_or_name required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/BrowserPool' description: Browser pool details '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' security: - bearerAuth: [] components: schemas: 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 memory: allOf: - $ref: '#/components/schemas/BrowserMemory' description: Memory allocated to newly-warmed browsers in this pool. 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 Region: description: | Geographic region for hosting browser sessions or pools. enum: - us-east - us-west - eu-west - ap-southeast type: string 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 BrowserMemory: description: Memory allocated to the browser session. enum: - 1GiB - 2GiB - 6GiB - 8GiB - 16GiB example: 8GiB type: string BrowserNetworkConfig: description: | Network configuration for a browser session or browser pool. properties: allowed_hosts: description: > Egress allowlist for a browser session: the only destinations the browser may reach through Kernel-managed egress. Any other destination is refused with a 403 whose X-Kernel-Proxy-Error header is network_policy_denied, so pages cannot load or send data to unlisted hosts, including with fetch() and WebSockets. Omit the field for unfiltered egress; an empty list is invalid. The allowlist applies from the browser's first request, and start_url must be allowed by it. Entries are exact hostnames ("example.com"), one leading "*." wildcard that matches subdomains at any depth but not the domain itself ("*.example.com" matches api.example.com, not example.com), public IPv4 addresses ("8.8.8.8"), bracketed public IPv6 addresses ("[2001:4860:4860::8888]"), or public CIDR ranges in canonical form ("8.8.4.0/24", "2001:4860::/32"). IP and CIDR entries only match destinations written as an IP address, never hostnames that resolve into the range. Entries cannot include ports, paths, or schemes, and match every port on their host. Wildcards over a public suffix ("*.com", "*.github.io") and private or reserved IP ranges are rejected, as are entries that overlap private_hosts. Enforced at Kernel's egress proxy only: destinations in private_hosts, and processes in the browser VM that do not use the browser's proxy, are not filtered, and Kernel's own control traffic is always allowed. Requires proxy v3. Not supported on browser pools. example: - example.com - '*.example.com' items: maxLength: 253 type: string maxItems: 100 minItems: 1 type: array 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 proxy_routes: description: > Per-destination proxy routes for a browser session. After setup, a destination hostname is matched against every route's hosts, regardless of port; route order does not matter. An exact hostname beats a wildcard, and a longer wildcard suffix beats a shorter one (for a.b.example.com: "a.b.example.com" > "*.b.example.com" > "*.example.com"). A host pattern may appear in only one route. "*.example.com" matches subdomains only, not example.com. A matched request selects the route's proxy instead of the session's top-level proxy (including mode: direct); the route proxy's own bypass_hosts still apply. If the route proxy becomes unavailable, matched requests fail closed without falling back. Requests that match no route use the session's default egress from the top-level proxy field (or the browser default when proxy is omitted: stealth proxy or direct egress). Routes take effect once the session is created; start_url and other traffic during browser setup use the top-level proxy. Setting routes requires proxy v3. Not supported on browser pools. items: $ref: '#/components/schemas/BrowserProxyRoute' maxItems: 10 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. storage: $ref: '#/components/schemas/BrowserTelemetryStorageConfig' description: >- Whether the session's captured telemetry is persisted to Kernel storage. Omitted for browsers created before this setting existed, which persist it. 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 BrowserProxyRoute: additionalProperties: false properties: hosts: description: > Exact hostnames or leading *. wildcard patterns (subdomains only); patterns cannot include ports, and matching ignores the destination port. Hosts not matched by any route use the session's top-level proxy (or the browser default when proxy is omitted). items: maxLength: 253 type: string maxItems: 50 minItems: 1 type: array proxy: $ref: '#/components/schemas/BrowserProxyRouteTarget' required: - hosts - proxy 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), screenshot and platform are off by default and are opt-in: set enabled=true to capture them. properties: captcha: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: Captcha solver tasks and visible challenge 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/BrowserTelemetryControlConfig' description: >- Agent-driven actions against the browser — computer-control calls, Playwright code execution, screenshots, clipboard access, and browser-control commands sent over the CDP proxy. 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. platform: $ref: '#/components/schemas/BrowserTelemetryCategoryConfig' description: >- In-VM API calls that manage the browser VM rather than drive the browser (recording, filesystem, process, telemetry and browser configuration). Mostly platform-induced; off by default and must be opted into. 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 BrowserTelemetryStorageConfig: description: Kernel storage state for a session's captured telemetry. properties: enabled: description: >- Whether captured telemetry is persisted to Kernel storage. When off, the session's events are only available on the live stream and through any configured export. type: boolean type: object BrowserProxyRouteTarget: additionalProperties: false description: >- Select an active non-direct proxy by ID or name. Responses always use ID. oneOf: - required: - id - required: - name properties: id: minLength: 1 type: string name: minLength: 1 type: string 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), screenshot and platform default to false; set true to opt in. type: boolean type: object BrowserTelemetryControlConfig: description: >- Configuration for the control category. Same enabled semantics as any other category, plus settings for the browser-control commands the CDP proxy reports. properties: cdp: $ref: '#/components/schemas/BrowserTelemetryCdpControlConfig' description: >- Settings for the cdp_command events the CDP proxy reports. Merged independently of enabled, so a later update that only sets enabled keeps the current exclusion list. enabled: description: >- Whether this category is captured. Control is on by default; set false to opt out. 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 BrowserTelemetryCdpControlConfig: description: Settings for the cdp_command events the CDP proxy reports. properties: excluded_methods: description: >- Methods to leave out of the cdp_command stream. Omit the list to keep the current one; send an empty list to report every supported method again. Exclusion is a telemetry setting only: an excluded command is still relayed to the browser unchanged, it simply produces no event. Use it to drop the highest-volume methods — Input.dispatchMouseEvent during a humanized cursor path, or Page.captureScreenshot under a screencast — without turning the whole category off. Excluded commands are counted in cdp_disconnect.telemetry_excluded. items: $ref: '#/components/schemas/BrowserCdpCommandMethod' type: array type: object BrowserCdpCommandMethod: description: > A browser-control CDP method the proxy reports. The set covers the commands an agent drives the browser with; configuration, DOM and Runtime bookkeeping, and Chrome-specific UI commands are outside it. Canonical definitions: devtools-protocol@2d019e73. enum: - Input.dispatchMouseEvent - Input.dispatchKeyEvent - Input.insertText - Input.imeSetComposition - Input.dispatchTouchEvent - Input.dispatchDragEvent - Input.cancelDragging - Input.emulateTouchFromMouseEvent - Input.synthesizePinchGesture - Input.synthesizeScrollGesture - Input.synthesizeTapGesture - DOM.setFileInputFiles - DOM.focus - DOM.scrollIntoViewIfNeeded - Page.bringToFront - Page.captureScreenshot - Page.captureSnapshot - Page.handleJavaScriptDialog - Page.navigate - Page.navigateToHistoryEntry - Page.reload - Page.printToPDF - Page.startScreencast - Page.stopScreencast - Page.stopLoading - Page.close - Page.setWebLifecycleState - Target.activateTarget - Target.closeTarget - Target.createTarget - Target.createBrowserContext - Target.disposeBrowserContext - Target.openDevTools - Browser.cancelDownload - Browser.close - Browser.setWindowBounds - Browser.setContentsSize - Autofill.trigger type: string responses: 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 NotFound: content: application/json: schema: $ref: '#/components/schemas/Error' description: Resource not found InternalError: content: application/json: schema: $ref: '#/components/schemas/Error' description: Internal Server Error securitySchemes: bearerAuth: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.