> ## Documentation Index > Fetch the complete documentation index at: https://tbd-6fc993ce-mintlify-add-deploy-button-docs-27400.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.yaml post /browser_pools/{id_or_name}/acquire 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: Invocations description: Invoke actions and stream or query invocation status and events. - name: Browsers description: >- Create and manage browser sessions, filesystem, processes, logs, and replays. - name: Proxies description: Create and manage proxy configurations for routing browser traffic. - name: Deployments description: Create and manage app deployments and stream deployment events. - name: Apps description: List applications and versions. - name: Profiles description: Create, list, retrieve, and delete browser profiles. - 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: Agent Auth description: Agent authentication flow endpoints for hosted credential capture. 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: - name: id_or_name in: path required: true schema: type: string description: Browser pool ID or name requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BrowserPoolAcquireRequest' responses: '200': description: Browser acquired successfully content: application/json: schema: $ref: '#/components/schemas/Browser' '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' '500': $ref: '#/components/responses/InternalError' security: - bearerAuth: [] components: schemas: BrowserPoolAcquireRequest: type: object description: Request body for acquiring a browser from the pool. properties: acquire_timeout_seconds: type: integer 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. required: [] Browser: type: object properties: created_at: type: string format: date-time description: When the browser session was created. cdp_ws_url: type: string description: >- Websocket URL for Chrome DevTools Protocol connections to the browser session example: wss://api.onkernel.com/browser/cdp?jwt=eyJ0eXAi... browser_live_view_url: type: string description: >- Remote URL for live viewing the browser session. Only available for non-headless browsers. example: https://api.onkernel.com/browser/remote?jwt=eyJ0eXAi... headless: type: boolean description: Whether the browser session is running in headless mode. example: false stealth: type: boolean description: Whether the browser session is running in stealth mode. example: false session_id: type: string description: Unique identifier for the browser session example: htzv5orfit78e1m2biiifpbv persistence: $ref: '#/components/schemas/BrowserPersistence' timeout_seconds: type: integer description: >- The number of seconds of inactivity before the browser session is terminated. profile: $ref: '#/components/schemas/Profile' proxy_id: type: string description: ID of the proxy associated with this browser session, if any. viewport: $ref: '#/components/schemas/BrowserViewport' kiosk_mode: type: boolean description: Whether the browser session is running in kiosk mode. example: false deleted_at: type: string format: date-time description: >- When the browser session was soft-deleted. Only present for deleted sessions. required: - created_at - cdp_ws_url - session_id - stealth - headless - timeout_seconds BrowserPersistence: type: object description: 'DEPRECATED: Use timeout_seconds (up to 72 hours) and Profiles instead.' deprecated: true x-deprecated-reason: Use timeout_seconds (up to 72 hours) and Profiles instead properties: id: type: string description: 'DEPRECATED: Unique identifier for the persistent browser session.' example: my-awesome-browser-for-user-1234 required: - id Profile: type: object description: Browser profile metadata. properties: id: type: string description: Unique identifier for the profile name: type: string nullable: true description: Optional, easier-to-reference name for the profile created_at: type: string format: date-time description: Timestamp when the profile was created updated_at: type: string format: date-time description: Timestamp when the profile was last updated last_used_at: type: string format: date-time description: Timestamp when the profile was last used required: - id - created_at BrowserViewport: type: object description: > Initial browser window size in pixels with optional refresh rate. If omitted, image defaults apply (1920x1080@25). Only specific viewport configurations are supported. The server will reject unsupported combinations. Supported resolutions are: 2560x1440@10, 1920x1080@25, 1920x1200@25, 1440x900@25, 1280x800@60, 1024x768@60, 1200x800@60 If refresh_rate is not provided, it will be automatically determined from the width and height if they match a supported configuration exactly. Note: Higher resolutions may affect the responsiveness of live view browser properties: width: type: integer description: Browser window width in pixels. minimum: 320 maximum: 7680 example: 1280 height: type: integer description: Browser window height in pixels. minimum: 240 maximum: 4320 example: 800 refresh_rate: type: integer description: >- Display refresh rate in Hz. If omitted, automatically determined from width and height. example: 60 required: - width - height 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' 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 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' NotFound: description: Resource not found 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 ````