> ## 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 browsers for an invocation > Returns all active browser sessions created within the specified invocation. ## OpenAPI ````yaml https://api.onkernel.com/spec.json get /invocations/{id}/browsers 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: /invocations/{id}/browsers: get: tags: - Invocations summary: List browsers for an invocation description: >- Returns all active browser sessions created within the specified invocation. operationId: getInvocationsBrowsersById parameters: - description: Invocation ID in: path name: id required: true schema: type: string responses: '200': content: application/json: schema: properties: browsers: items: $ref: '#/components/schemas/Browser' type: array required: - browsers type: object description: List of browsers for this invocation '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' security: - bearerAuth: [] components: schemas: 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 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 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 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 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 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 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 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 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 ````