> ## 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. # Acquire a browser from the pool > Long-polling endpoint to acquire a browser from the pool. Returns immediately when a browser is available, or returns 204 No Content when the poll times out. The client should retry the request to continue waiting for a browser. The acquired browser will use the pool's timeout_seconds for its idle timeout. ## OpenAPI ````yaml https://api.onkernel.com/spec.json post /browser_pools/{id_or_name}/acquire 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/{id_or_name}/acquire: post: tags: - Browser Pools summary: Acquire a browser from the pool description: > Long-polling endpoint to acquire a browser from the pool. Returns immediately when a browser is available, or returns 204 No Content when the poll times out. The client should retry the request to continue waiting for a browser. The acquired browser will use the pool's timeout_seconds for its idle timeout. operationId: acquireFromBrowserPoolByIdOrName parameters: - description: Browser pool ID or name in: path name: id_or_name required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/BrowserPoolAcquireRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/Browser' description: Browser acquired successfully '204': description: >- Poll timed out, no browser available. Retry the request to continue waiting. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '500': $ref: '#/components/responses/InternalError' security: - bearerAuth: [] components: schemas: BrowserPoolAcquireRequest: description: Request body for acquiring a browser from the pool. properties: acquire_timeout_seconds: description: >- Maximum number of seconds to wait for a browser to be available. Defaults to the calculated time it would take to fill the pool at the currently configured fill rate. type: integer name: description: > Optional human-readable name for the acquired browser session, used to find it later in the dashboard. Must be unique among active sessions within the pool's project. Applies to this lease only and is cleared when the browser is released back to the pool. example: checkout-flow-1 maxLength: 255 minLength: 1 pattern: ^[a-zA-Z0-9._-]{1,255}$ type: string start_url: description: >- Optional URL to navigate the acquired browser to. Overrides the pool's start_url for this acquire only. Best-effort: failures to navigate do not fail the acquire. example: https://example.com type: string tags: $ref: '#/components/schemas/Tags' description: > Optional user-defined key-value tags for the acquired browser session, used to find and group sessions later. Applies to this lease only and are cleared when the browser is released back to the pool. Up to 50 pairs. telemetry: $ref: '#/components/schemas/BrowserTelemetryRequestConfig' description: > Telemetry override for the acquired browser, applied to this lease only. Merges onto the browser's current (pool-inherited) telemetry using the same per-category semantics as PATCH /browsers: provided categories override the current configuration, omitted categories are inherited. Set enabled to true to resolve the config fresh from the default set, or enabled to false to stop capture. When the browser is released back to the pool with reuse, its telemetry is reset to the pool's baseline, so the override does not carry over to the next lease. nullable: true required: [] type: object Browser: properties: base_url: description: Metro-API HTTP base URL for this browser session. example: https://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/kernel type: string browser_live_view_url: description: >- Remote URL for live viewing the browser session. Only available for non-headless browsers. example: >- https://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/live?jwt=eyJ0eXAi... type: string cdp_ws_url: description: >- Websocket URL for Chrome DevTools Protocol connections to the browser session example: >- wss://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/cdp?jwt=eyJ0eXAi... type: string chrome_policy: additionalProperties: true description: > Custom Chrome enterprise policy overrides that were applied to this browser session, if any. Echoed back for verification. Keys are Chrome enterprise policy names. type: object created_at: description: When the browser session was created. format: date-time type: string deleted_at: description: >- When the browser session was soft-deleted. Only present for deleted sessions. format: date-time type: string gpu: description: >- Whether GPU acceleration is enabled for the browser session (only supported for headful sessions). example: false type: boolean headless: description: Whether the browser session is running in headless mode. example: false type: boolean kiosk_mode: description: Whether the browser session is running in kiosk mode. example: false type: boolean name: description: >- Human-readable name of the browser session, if one was set at creation. example: checkout-flow-1 type: string network: $ref: '#/components/schemas/BrowserNetworkConfig' description: >- Network configuration the session was created with, if any. Omitted when the session has no network configuration. pool: $ref: '#/components/schemas/BrowserPoolRef' profile: $ref: '#/components/schemas/Profile' profile_save_changes: description: >- Whether changes made during this browser session are saved back to its profile when the session ends. Omitted when no profile is attached. type: boolean proxy: $ref: '#/components/schemas/BrowserProxy' description: Resolved proxy configuration for this browser session. proxy_id: deprecated: true description: >- ID of the proxy associated with this browser session, if any. Deprecated in favor of proxy. type: string x-deprecated-reason: Use proxy instead. region: $ref: '#/components/schemas/Region' description: > Geographic region of the browser session. Fixed once the session is created. session_id: description: Unique identifier for the browser session example: htzv5orfit78e1m2biiifpbv type: string start_url: description: >- URL the session was asked to navigate to on creation, if any. Recorded for debugging. Navigation is fire-and-forget — the URL is dispatched to the browser without waiting for it to load, and any errors (DNS failure, bad status, timeout) are silently dropped. Captures what was requested, not what the browser actually loaded. example: https://example.com type: string stealth: description: Whether the browser session is running in stealth mode. example: false type: boolean tags: $ref: '#/components/schemas/Tags' description: >- User-defined key-value tags that were set on this browser session, if any. Echoed back when present. telemetry: $ref: '#/components/schemas/BrowserTelemetryConfig' description: Active telemetry configuration for the session, if any. nullable: true timeout_seconds: description: >- The number of seconds of inactivity before the browser session is terminated. type: integer usage: $ref: '#/components/schemas/BrowserUsage' viewport: $ref: '#/components/schemas/BrowserViewport' webdriver_ws_url: description: Websocket URL for WebDriver BiDi connections to the browser session example: >- wss://proxy.yul-upbeat-herschel.onkernel.com:8443/browser/webdriver/session?jwt=eyJ0eXAi... type: string required: - created_at - cdp_ws_url - webdriver_ws_url - session_id - region - stealth - headless - timeout_seconds type: object Tags: additionalProperties: maxLength: 256 minLength: 0 pattern: ^[A-Za-z0-9 _.:/=+@-]*$ type: string description: User-defined key-value tags. example: env: staging team: backend maxProperties: 50 propertyNames: maxLength: 128 minLength: 1 pattern: ^[A-Za-z0-9 _.:/=+@-]+$ type: string type: object BrowserTelemetryRequestConfig: description: Telemetry request configuration for a browser session. properties: 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. enabled: 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. type: boolean export: $ref: '#/components/schemas/BrowserTelemetryExportRequestConfig' description: >- Where to export this session's captured telemetry. Omit to capture without exporting. 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 BrowserPoolRef: description: Browser pool this session was acquired from, if any. properties: id: description: Browser pool ID type: string name: description: Browser pool name, if set type: string required: - id type: object Profile: description: Browser profile metadata. properties: created_at: description: Timestamp when the profile was created format: date-time type: string id: description: Unique identifier for the profile type: string last_used_at: description: Timestamp when the profile was last used format: date-time type: string name: description: Optional, easier-to-reference name for the profile nullable: true type: string updated_at: description: Timestamp when the profile was last updated format: date-time type: string required: - id - created_at type: object BrowserProxy: additionalProperties: false description: >- Resolved proxy configuration for a browser session. Selected proxies are returned by stable ID. oneOf: - required: - mode - required: - id - required: - name properties: id: description: Selected proxy ID. minLength: 1 type: string mode: $ref: '#/components/schemas/BrowserProxyMode' name: description: Selected proxy name. minLength: 1 type: string type: object Region: description: | Geographic region for hosting browser sessions or pools. enum: - us-east - eu-west type: string 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 BrowserUsage: description: Session usage metrics. properties: uptime_ms: description: Time in milliseconds the session was actively running. type: integer required: - uptime_ms 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 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 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 BrowserTelemetryExportRequestConfig: description: >- Export destinations for a session's captured telemetry, by protocol. Honored when creating a browser, including the browser a managed auth connection creates for a login. Browser pools do not support export and reject it; on a browser update it is ignored, so the session keeps the destination it was created with. properties: otlp: $ref: '#/components/schemas/BrowserTelemetryOTLPExportRequestConfig' description: >- Export captured telemetry over OTLP to one of the org's configured destinations. type: object BrowserProxyMode: description: > Proxy egress mode. direct forces no proxy regardless of stealth. default uses the browser's stealth-derived default: Kernel's default stealth proxy when stealth=true, or direct egress when stealth=false. default is primarily useful on browser update to restore the browser default after selected-proxy egress. enum: - direct - default type: string x-enum-varnames: - Direct - Default 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 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 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 BrowserTelemetryOTLPExportRequestConfig: description: OTLP export settings for a browser session. properties: destination: $ref: '#/components/schemas/OTLPDestinationRef' description: >- OTLP destination to export this session's captured telemetry to. Provide either id or name. Requires telemetry capture to be enabled. enabled: description: >- Whether to export captured telemetry over OTLP. Setting destination implies enabled=true, so this only needs to be set explicitly to disable export (enabled=false with a destination is rejected). 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 OTLPDestinationRef: description: > OTLP destination selection. Provide either id or name. The destination must belong to the caller's org. When selecting by name, the name must match exactly one destination in the org. Ambiguous names return a 400; use id for stable references. oneOf: - required: - id - required: - name properties: id: description: OTLP destination ID type: string name: description: OTLP destination name type: string 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 NotFound: content: application/json: schema: $ref: '#/components/schemas/Error' description: Resource not found Conflict: content: application/json: schema: $ref: '#/components/schemas/Error' description: Conflict – resource already exists InternalError: content: application/json: schema: $ref: '#/components/schemas/Error' description: Internal Server Error securitySchemes: bearerAuth: scheme: bearer type: http ````