Kernel Browser Telemetry API
Stream live telemetry events from a browser session.
OpenAPI Specification
openapi: 3.1.0
info:
title: Kernel API Keys Browser Telemetry 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: Browser Telemetry
description: Stream live telemetry events from a browser session.
paths:
/browsers/{id}/telemetry:
get:
summary: Stream telemetry events via SSE
description: 'Streams browser telemetry events as a server-sent events (SSE) stream. The stream closes when the browser session terminates. Each event frame includes an id: field containing a monotonically increasing sequence number; pass it as Last-Event-ID on reconnect to resume without gaps. The event: field is never set; all frames carry JSON in the data: field. A keepalive comment frame is sent every 15 seconds when no events arrive. Returns 404 if the browser session does not exist. If telemetry was not enabled on the session, the stream opens but no events are delivered.
'
operationId: streamBrowserTelemetry
tags:
- Browser Telemetry
security:
- bearerAuth: []
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Browser session ID
- name: Last-Event-ID
in: header
schema:
type: string
description: Last event sequence number for SSE reconnection (sent by SSE clients on reconnect)
responses:
'200':
description: SSE stream of telemetry events
headers:
X-SSE-Content-Type:
description: Media type of SSE data events (always application/json).
schema:
type: string
const: application/json
content:
text/event-stream:
schema:
$ref: '#/components/schemas/BrowserTelemetryEventEnvelope'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
x-codeSamples:
- lang: JavaScript
source: "import Kernel from '@onkernel/sdk';\n\nconst client = new Kernel({\n apiKey: process.env['KERNEL_API_KEY'], // This is the default and can be omitted\n});\n\nconst response = await client.browsers.telemetry.stream('id');\n\nconsole.log(response.event);"
- lang: Python
source: "import os\nfrom kernel import Kernel\n\nclient = Kernel(\n api_key=os.environ.get(\"KERNEL_API_KEY\"), # This is the default and can be omitted\n)\nfor telemetry in client.browsers.telemetry.stream(\n id=\"id\",\n):\n print(telemetry)"
- lang: Go
source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/kernel/kernel-go-sdk\"\n\t\"github.com/kernel/kernel-go-sdk/option\"\n)\n\nfunc main() {\n\tclient := kernel.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tstream := client.Browsers.Telemetry.StreamStreaming(\n\t\tcontext.TODO(),\n\t\t\"id\",\n\t\tkernel.BrowserTelemetryStreamParams{},\n\t)\n\tfor stream.Next() {\n\t\tfmt.Printf(\"%+v\\n\", stream.Current())\n\t}\n\terr := stream.Err()\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n}\n"
components:
schemas:
BrowserNetworkRequestEvent:
type: object
description: A browser network request sent event.
required:
- ts
- type
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: network_request
source:
$ref: '#/components/schemas/BrowserEventSource'
data:
allOf:
- $ref: '#/components/schemas/BrowserEventContext'
- type: object
properties:
request_id:
type: string
description: CDP request identifier, unique within the session.
method:
type: string
description: HTTP method as sent on the wire (e.g. GET, POST).
document_url:
type: string
description: URL of the document that initiated the request.
headers:
$ref: '#/components/schemas/BrowserHttpHeaders'
description: Request headers.
resource_type:
type: string
description: CDP Network.ResourceType for the request, passed through as-is from Chrome. Known values include Document, Fetch, XHR, Script, Stylesheet, Image, Media, Font, TextTrack, EventSource, WebSocket, Manifest, Prefetch, Other, and more.
initiator_type:
type: string
description: CDP Initiator.type indicating what caused the request, passed through as-is from Chrome. Known values include script, parser, preload, and other.
post_data:
type: string
description: Request body for POST/PUT requests, if available.
is_redirect:
type: boolean
description: True if this request is the result of a redirect.
redirect_url:
type: string
description: Original URL before the redirect, present when is_redirect is true.
truncated:
type: boolean
description: True if the data field was truncated due to size limits.
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
BrowserInteractionScrollSettledEvent:
type: object
description: A browser scroll settled event emitted after scroll position stops changing, captured via injected page script.
required:
- ts
- type
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: interaction_scroll_settled
source:
$ref: '#/components/schemas/BrowserEventSource'
data:
allOf:
- $ref: '#/components/schemas/BrowserEventContext'
- type: object
properties:
from_x:
type: integer
description: Scroll x-position at the start of the scroll gesture in CSS pixels.
from_y:
type: integer
description: Scroll y-position at the start of the scroll gesture in CSS pixels.
to_x:
type: integer
description: Final scroll x-position after the gesture settled in CSS pixels.
to_y:
type: integer
description: Final scroll y-position after the gesture settled in CSS pixels.
target_selector:
type: string
description: CSS selector path to the scrolled element.
truncated:
type: boolean
description: True if the data field was truncated due to size limits.
BrowserMonitorInitFailedEvent:
type: object
description: The CDP session could not be initialized.
required:
- ts
- type
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: monitor_init_failed
source:
$ref: '#/components/schemas/BrowserEventSource'
data:
type: object
additionalProperties: false
properties:
step:
type: string
description: The CDP method or initialization step that failed (e.g. Target.setAutoAttach).
truncated:
type: boolean
description: True if the data field was truncated due to size limits.
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'
BrowserMonitorDisconnectedEvent:
type: object
description: The CDP connection to Chrome was lost. Telemetry events may be dropped until monitor_reconnected arrives. Treat any in-progress computed state (network_idle, page_layout_settled) as unreliable until then.
required:
- ts
- type
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: monitor_disconnected
source:
$ref: '#/components/schemas/BrowserEventSource'
data:
type: object
additionalProperties: false
properties:
reason:
type: string
description: 'Reason for the disconnection. chrome_restarted: Chrome process restarted.'
enum:
- chrome_restarted
truncated:
type: boolean
description: True if the data field was truncated due to size limits.
BrowserPageNavigationSettledEvent:
type: object
description: Emitted when page_dom_content_loaded and page_layout_settled have both fired for the same navigation, indicating the page is loaded and visually stable. Independent of network_idle; a single pending request does not block it.
required:
- ts
- type
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: page_navigation_settled
source:
$ref: '#/components/schemas/BrowserEventSource'
data:
$ref: '#/components/schemas/BrowserEventContext'
truncated:
type: boolean
description: True if the data field was truncated due to size limits.
BrowserNetworkIdleEvent:
type: object
description: A browser network idle event emitted after a 500ms quiet period with no in-flight HTTP requests.
required:
- ts
- type
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: network_idle
source:
$ref: '#/components/schemas/BrowserEventSource'
data:
$ref: '#/components/schemas/BrowserEventContext'
truncated:
type: boolean
description: True if the data field was truncated due to size limits.
BrowserPageTabOpenedEvent:
type: object
description: A new browser tab or target was opened (CDP Target.attachedToTarget for page targets). Fires before a CDP session is attached to the new target, so session_id, frame_id, loader_id, and nav_seq are absent; this event does not compose BrowserEventContext. Consumers reading context fields generically should treat it as a special case.
required:
- ts
- type
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: page_tab_opened
source:
$ref: '#/components/schemas/BrowserEventSource'
data:
type: object
additionalProperties: false
properties:
target_id:
type: string
description: CDP target identifier for the newly opened tab.
target_type:
$ref: '#/components/schemas/BrowserTargetType'
url:
type: string
description: Initial URL of the new tab.
title:
type: string
description: Initial page title of the new tab.
opener_id:
type: string
description: Target identifier of the tab that opened this one, if any.
truncated:
type: boolean
description: True if the data field was truncated due to size limits.
BrowserPageLcpEvent:
type: object
description: A browser Largest Contentful Paint (LCP) event from the Performance Timeline API.
required:
- ts
- type
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: page_lcp
source:
$ref: '#/components/schemas/BrowserEventSource'
data:
allOf:
- $ref: '#/components/schemas/BrowserEventContext'
- type: object
properties:
source_frame_id:
type: string
description: CDP frame identifier of the frame where the LCP element was rendered.
time:
type: number
description: Performance Timeline timestamp of the LCP entry in milliseconds.
lcp_details:
type: object
additionalProperties: false
description: LargestContentfulPaint attributes from the Performance Timeline entry.
properties:
render_time:
type: number
description: Render time of the LCP element in milliseconds; 0 for cross-origin images without Timing-Allow-Origin.
load_time:
type: number
description: Load time of the LCP element in milliseconds.
size:
type: number
description: Visible area of the LCP element in pixels squared.
element_id:
type: string
description: id attribute of the LCP element, if present.
url:
type: string
description: URL of the LCP element for image or video elements.
node_id:
type: integer
description: CDP DOM node identifier of the LCP element.
truncated:
type: boolean
description: True if the data field was truncated due to size limits.
BrowserPageLayoutShiftEvent:
type: object
description: A browser cumulative layout shift (CLS) event from the Performance Timeline API.
required:
- ts
- type
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: page_layout_shift
source:
$ref: '#/components/schemas/BrowserEventSource'
data:
allOf:
- $ref: '#/components/schemas/BrowserEventContext'
- type: object
properties:
source_frame_id:
type: string
description: CDP frame identifier of the frame where the layout shift occurred.
time:
type: number
description: Performance Timeline timestamp of the layout shift in milliseconds.
duration:
type: number
description: Duration of the layout shift entry in milliseconds (always 0 for layout shifts per spec).
layout_shift_details:
type: object
additionalProperties: false
description: PerformanceLayoutShift attributes from the Performance Timeline entry.
properties:
value:
type: number
description: Layout shift score for this entry (contribution to CLS).
had_recent_input:
type: boolean
description: True if the layout shift was preceded by user input within 500ms, excluding it from CLS.
truncated:
type: boolean
description: True if the data field was truncated due to size limits.
BrowserInteractionClickEvent:
type: object
description: A browser user click event captured via injected page script.
required:
- ts
- type
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: interaction_click
source:
$ref: '#/components/schemas/BrowserEventSource'
data:
allOf:
- $ref: '#/components/schemas/BrowserEventContext'
- type: object
properties:
x:
type: integer
description: Viewport x-coordinate of the click in CSS pixels.
y:
type: integer
description: Viewport y-coordinate of the click in CSS pixels.
selector:
type: string
description: CSS selector path to the clicked element.
tag:
type: string
description: HTML tag name of the clicked element in uppercase (e.g. BUTTON, A, DIV).
text:
type: string
description: Visible text content of the clicked element, trimmed.
truncated:
type: boolean
description: True if the data field was truncated due to size limits.
BrowserPageLayoutSettledEvent:
type: object
description: A browser layout settled event emitted 1 second after page load with no intervening layout shifts, indicating visual stability. Each layout shift resets the 1-second timer.
required:
- ts
- type
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: page_layout_settled
source:
$ref: '#/components/schemas/BrowserEventSource'
data:
$ref: '#/components/schemas/BrowserEventContext'
truncated:
type: boolean
description: True if the data field was truncated due to size limits.
BrowserTelemetryEvent:
oneOf:
- $ref: '#/components/schemas/BrowserConsoleLogEvent'
- $ref: '#/components/schemas/BrowserConsoleErrorEvent'
- $ref: '#/components/schemas/BrowserNetworkRequestEvent'
- $ref: '#/components/schemas/BrowserNetworkResponseEvent'
- $ref: '#/components/schemas/BrowserNetworkLoadingFailedEvent'
- $ref: '#/components/schemas/BrowserNetworkIdleEvent'
- $ref: '#/components/schemas/BrowserPageNavigationEvent'
- $ref: '#/components/schemas/BrowserPageDomContentLoadedEvent'
- $ref: '#/components/schemas/BrowserPageLoadEvent'
- $ref: '#/components/schemas/BrowserPageTabOpenedEvent'
- $ref: '#/components/schemas/BrowserPageLayoutShiftEvent'
- $ref: '#/components/schemas/BrowserPageLcpEvent'
- $ref: '#/components/schemas/BrowserPageLayoutSettledEvent'
- $ref: '#/components/schemas/BrowserPageNavigationSettledEvent'
- $ref: '#/components/schemas/BrowserInteractionClickEvent'
- $ref: '#/components/schemas/BrowserInteractionKeyEvent'
- $ref: '#/components/schemas/BrowserInteractionScrollSettledEvent'
- $ref: '#/components/schemas/BrowserMonitorScreenshotEvent'
- $ref: '#/components/schemas/BrowserMonitorDisconnectedEvent'
- $ref: '#/components/schemas/BrowserMonitorReconnectedEvent'
- $ref: '#/components/schemas/BrowserMonitorReconnectFailedEvent'
- $ref: '#/components/schemas/BrowserMonitorInitFailedEvent'
discriminator:
propertyName: type
mapping:
console_log: '#/components/schemas/BrowserConsoleLogEvent'
console_error: '#/components/schemas/BrowserConsoleErrorEvent'
network_request: '#/components/schemas/BrowserNetworkRequestEvent'
network_response: '#/components/schemas/BrowserNetworkResponseEvent'
network_loading_failed: '#/components/schemas/BrowserNetworkLoadingFailedEvent'
network_idle: '#/components/schemas/BrowserNetworkIdleEvent'
page_navigation: '#/components/schemas/BrowserPageNavigationEvent'
page_dom_content_loaded: '#/components/schemas/BrowserPageDomContentLoadedEvent'
page_load: '#/components/schemas/BrowserPageLoadEvent'
page_tab_opened: '#/components/schemas/BrowserPageTabOpenedEvent'
page_layout_shift: '#/components/schemas/BrowserPageLayoutShiftEvent'
page_lcp: '#/components/schemas/BrowserPageLcpEvent'
page_layout_settled: '#/components/schemas/BrowserPageLayoutSettledEvent'
page_navigation_settled: '#/components/schemas/BrowserPageNavigationSettledEvent'
interaction_click: '#/components/schemas/BrowserInteractionClickEvent'
interaction_key: '#/components/schemas/BrowserInteractionKeyEvent'
interaction_scroll_settled: '#/components/schemas/BrowserInteractionScrollSettledEvent'
monitor_screenshot: '#/components/schemas/BrowserMonitorScreenshotEvent'
monitor_disconnected: '#/components/schemas/BrowserMonitorDisconnectedEvent'
monitor_reconnected: '#/components/schemas/BrowserMonitorReconnectedEvent'
monitor_reconnect_failed: '#/components/schemas/BrowserMonitorReconnectFailedEvent'
monitor_init_failed: '#/components/schemas/BrowserMonitorInitFailedEvent'
description: 'Union type representing any browser telemetry event. Discriminated on `type`. Events with a `monitor_` prefix (monitor_screenshot, monitor_disconnected, monitor_reconnected, monitor_reconnect_failed, monitor_init_failed) are always emitted regardless of the category configuration in BrowserTelemetryConfig. All other event types are controlled by the per-category enable/disable flags.
'
BrowserTelemetryEventEnvelope:
type: object
description: 'Envelope wrapping a browser telemetry event with its monotonic sequence number. Each SSE data: frame carries one envelope as JSON. The seq value is also emitted as the SSE id: field so clients can pass it as Last-Event-ID on reconnect.
'
required:
- seq
- event
properties:
seq:
type: integer
format: int64
minimum: 1
description: 'Process-monotonic sequence number assigned by the browser VM. Pass as Last-Event-ID on reconnect to resume without gaps. Gaps in received seq values indicate dropped events.
'
event:
$ref: '#/components/schemas/BrowserTelemetryEvent'
additionalProperties: false
BrowserPageNavigationEvent:
type: object
description: A browser page navigation started event (CDP Page.frameNavigated). Carries nav context fields inline but not nav_seq, as this event resets the navigation epoch.
required:
- ts
- type
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: page_navigation
source:
$ref: '#/components/schemas/BrowserEventSource'
data:
type: object
additionalProperties: false
properties:
url:
type: string
description: URL navigated to.
frame_id:
type: string
description: CDP frame identifier of the navigated frame.
parent_frame_id:
type: string
description: Parent frame identifier for subframe navigations; absent for top-level navigations.
loader_id:
type: string
description: New CDP document loader identifier assigned for this navigation.
session_id:
type: string
description: CDP session identifier.
target_id:
type: string
description: Browser target identifier.
target_type:
$ref: '#/components/schemas/BrowserTargetType'
truncated:
type: boolean
description: True if the data field was truncated due to size limits.
BrowserCallStack:
type: object
description: CDP Runtime.StackTrace representing the JavaScript call stack at the time of an event. Fields use CDP naming conventions rather than snake_case to match the Chrome DevTools Protocol wire format.
required:
- callFrames
properties:
description:
type: string
description: Optional label for the stack trace (e.g. async cause).
callFrames:
type: array
description: Ordered list of call frames, outermost first.
items:
type: object
required:
- functionName
- scriptId
- url
- lineNumber
- columnNumber
properties:
functionName:
type: string
description: JavaScript function name, or empty string for anonymous functions.
scriptId:
type: string
description: CDP script identifier.
url:
type: string
description: URL or name of the script file.
lineNumber:
type: integer
description: Zero-based line number within the script.
columnNumber:
type: integer
description: Zero-based column number within the line.
parent:
$ref: '#/components/schemas/BrowserCallStack'
description: Parent stack trace for async stacks.
BrowserEventContext:
type: object
description: Browser event context stamped by the browser monitor onto all CDP-sourced events. Identifies the target, frame, and navigation epoch in which the event occurred.
properties:
session_id:
type: string
description: CDP session identifier for the target connection.
target_id:
type: string
description: Browser target identifier (stable across navigations within a tab).
target_type:
$ref: '#/components/schemas/BrowserTargetType'
frame_id:
type: string
description: CDP frame identifier within the target.
loader_id:
type: string
description: CDP document loader identifier, reset on each navigation.
url:
type: string
description: URL relevant to this event — page URL for navigation and page events, request URL for network events.
nav_seq:
type: integer
format: int64
description: Monotonically increasing navigation sequence number, incremented on each top-level navigation within the target.
BrowserConsoleLogEvent:
type: object
description: A browser console log event (console.log, console.info, console.warn, etc.).
required:
- ts
- type
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: console_log
source:
$ref: '#/components/schemas/BrowserEventSource'
data:
allOf:
- $ref: '#/components/schemas/BrowserEventContext'
- type: object
properties:
level:
type: string
description: CDP Runtime.consoleAPICalled type, passed through unfiltered from Chrome. error is routed to console_error events instead; all other CDP console types appear here. See CDP spec for the full enum.
text:
type: string
description: First console argument coerced to string.
args:
type: array
description: All console arguments coerced to strings.
items:
type: string
stack_trace:
$ref: '#/components/schemas/BrowserCallStack'
truncated:
type: boolean
description: True if the data field was truncated due to size limits.
BrowserTargetType:
type: string
description: CDP target type of the page that produced the event.
enum:
- page
- background_page
- service_worker
- shared_worker
- other
BrowserMonitorScreenshotEvent:
type: object
description: A periodic screenshot of the browser viewport.
required:
- ts
- type
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: monitor_screenshot
source:
$ref: '#/components/schemas/BrowserEventSource'
data:
type: object
additionalProperties: false
properties:
png:
type: string
contentEncoding: base64
description: Base64-encoded PNG screenshot of the browser viewport.
truncated:
type: boolean
description: True if the data field was truncated due to size limits.
BrowserPageDomContentLoadedEvent:
type: object
description: A browser DOMContentLoaded event (CDP Page.domContentEventFired).
required:
- ts
- type
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: page_dom_content_loaded
source:
$ref: '#/components/schemas/BrowserEventSource'
data:
allOf:
- $ref: '#/components/schemas/BrowserEventContext'
- type: object
properties:
cdp_timestamp:
type: number
description: Chrome monotonic clock value in seconds at which DOMContentLoaded fired, relative to browser process start (not Unix epoch). Use ts for wall-clock time.
truncated:
type: boolean
description: True if the data field was truncated due to size limits.
BrowserMonitorReconnectFailedEvent:
type: object
description: The CDP connection to Chrome could not be re-established after exhausting all reconnection attempts. No further telemetry events will arrive on this session.
required:
- ts
- type
- source
properties:
ts:
type: integer
format: int64
description: Event timestamp in Unix microseconds.
type:
type: string
const: monitor_reconnect_failed
source:
$ref: '#/components/schemas/BrowserEventSource'
data:
type: object
additionalProperties: false
properties:
reason:
type: string
description: 'Reason for the reconnection failure. reconnect_exhausted: all retry attempts were used up without successfully restoring the CDP connection.'
enum:
- reconnect_exhausted
truncated:
type: boolean
description: True if the data field was truncated due to size limits.
BrowserNetworkLoadingFailedEvent:
type: object
description: A browser network loading failed event. If the request was already in flight when CDP atta
# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kernel-so/refs/heads/main/openapi/kernel-so-browser-telemetry-api-openapi.yml