feat: Add GET /browsers/{id}/telemetry/events (read from S2)

stainless-app[bot] · stainless-app[bot] · commit 9a84bff15de4 · 2026-06-23T16:36:10.000Z
diff --git a/.stats.yml b/.stats.yml
@@ -1,4 +1,4 @@
-configured_endpoints: 121
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-01f7f21a2fc892da284edf6b7cfd340d2ce5d0a9eb7ad2b39a8daec27b093134.yml
-openapi_spec_hash: 21972930082b23d985faf285fd656c31
-config_hash: 3a50aee540dce69a53bb8942f5086f5e
+configured_endpoints: 122
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-7cde13c82c71b7a5fd64b592f853a7c999c0e0c02dce161e6126d0e99df3412b.yml
+openapi_spec_hash: 52cda226c70a248cbea3af6c52822b44
+config_hash: 99b2b2a25e8067ad9c9214e38e01d64c
diff --git a/api.md b/api.md
@@ -146,12 +146,14 @@ from kernel.types.browsers import (
     BrowserTelemetryCategoryConfig,
     BrowserTelemetryConfig,
     BrowserTelemetryEvent,
+    TelemetryEventsResponse,
     TelemetryStreamResponse,
 )
 ```
 
 Methods:
 
+- <code title="get /browsers/{id}/telemetry/events">client.browsers.telemetry.<a href="./src/kernel/resources/browsers/telemetry.py">events</a>(id, \*\*<a href="src/kernel/types/browsers/telemetry_events_params.py">params</a>) -> <a href="./src/kernel/types/browsers/telemetry_events_response.py">SyncOffsetPagination[TelemetryEventsResponse]</a></code>
 - <code title="get /browsers/{id}/telemetry/stream">client.browsers.telemetry.<a href="./src/kernel/resources/browsers/telemetry.py">stream</a>(id, \*\*<a href="src/kernel/types/browsers/telemetry_stream_params.py">params</a>) -> <a href="./src/kernel/types/browsers/telemetry_stream_response.py">TelemetryStreamResponse</a></code>
 
 ## Replays
diff --git a/src/kernel/resources/browsers/telemetry.py b/src/kernel/resources/browsers/telemetry.py
@@ -2,6 +2,9 @@
 
 from __future__ import annotations
 
+from typing import List
+from typing_extensions import Literal
+
 import httpx
 
 from ..._types import Body, Omit, Query, Headers, NotGiven, omit, not_given
@@ -15,8 +18,10 @@
     async_to_streamed_response_wrapper,
 )
 from ..._streaming import Stream, AsyncStream
-from ..._base_client import make_request_options
-from ...types.browsers import telemetry_stream_params
+from ...pagination import SyncOffsetPagination, AsyncOffsetPagination
+from ..._base_client import AsyncPaginator, make_request_options
+from ...types.browsers import telemetry_events_params, telemetry_stream_params
+from ...types.browsers.telemetry_events_response import TelemetryEventsResponse
 from ...types.browsers.telemetry_stream_response import TelemetryStreamResponse
 
 __all__ = ["TelemetryResource", "AsyncTelemetryResource"]
@@ -44,6 +49,91 @@ def with_streaming_response(self) -> TelemetryResourceWithStreamingResponse:
         """
         return TelemetryResourceWithStreamingResponse(self)
 
+    def events(
+        self,
+        id: str,
+        *,
+        category: List[
+            Literal[
+                "console",
+                "network",
+                "page",
+                "interaction",
+                "control",
+                "connection",
+                "system",
+                "screenshot",
+                "captcha",
+                "monitor",
+            ]
+        ]
+        | Omit = omit,
+        limit: int | Omit = omit,
+        offset: int | Omit = omit,
+        since: str | Omit = omit,
+        until: str | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> SyncOffsetPagination[TelemetryEventsResponse]:
+        """
+        Reads a page of telemetry events for the browser session in ascending sequence
+        order. To page through results, pass the X-Next-Offset value from the previous
+        response as offset and repeat while X-Has-More is true. Returns an empty list
+        when telemetry data is unavailable.
+
+        Args:
+          category: Restrict results to these event categories. Repeat the parameter for multiple
+              values.
+
+          limit: Maximum number of events per page. Defaults to 20.
+
+          offset: Opaque pagination cursor: pass the X-Next-Offset value from the previous
+              response to fetch the next page. When set, paging continues from this cursor and
+              since is ignored, while until still bounds the page. It is not an event's seq
+              field, so do not derive it from the response body.
+
+          since: Start of the window: an RFC-3339 timestamp, or a duration like 5m meaning that
+              long ago. Defaults to 5m. Ignored when offset is set.
+
+          until: End of the window (exclusive): an RFC-3339 timestamp, or a duration like 5m
+              meaning that long ago.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        if not id:
+            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
+        return self._get_api_list(
+            path_template("/browsers/{id}/telemetry/events", id=id),
+            page=SyncOffsetPagination[TelemetryEventsResponse],
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                query=maybe_transform(
+                    {
+                        "category": category,
+                        "limit": limit,
+                        "offset": offset,
+                        "since": since,
+                        "until": until,
+                    },
+                    telemetry_events_params.TelemetryEventsParams,
+                ),
+            ),
+            model=TelemetryEventsResponse,
+        )
+
     def stream(
         self,
         id: str,
@@ -123,6 +213,91 @@ def with_streaming_response(self) -> AsyncTelemetryResourceWithStreamingResponse
         """
         return AsyncTelemetryResourceWithStreamingResponse(self)
 
+    def events(
+        self,
+        id: str,
+        *,
+        category: List[
+            Literal[
+                "console",
+                "network",
+                "page",
+                "interaction",
+                "control",
+                "connection",
+                "system",
+                "screenshot",
+                "captcha",
+                "monitor",
+            ]
+        ]
+        | Omit = omit,
+        limit: int | Omit = omit,
+        offset: int | Omit = omit,
+        since: str | Omit = omit,
+        until: str | Omit = omit,
+        # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
+        # The extra values given here take precedence over values defined on the client or passed to this method.
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> AsyncPaginator[TelemetryEventsResponse, AsyncOffsetPagination[TelemetryEventsResponse]]:
+        """
+        Reads a page of telemetry events for the browser session in ascending sequence
+        order. To page through results, pass the X-Next-Offset value from the previous
+        response as offset and repeat while X-Has-More is true. Returns an empty list
+        when telemetry data is unavailable.
+
+        Args:
+          category: Restrict results to these event categories. Repeat the parameter for multiple
+              values.
+
+          limit: Maximum number of events per page. Defaults to 20.
+
+          offset: Opaque pagination cursor: pass the X-Next-Offset value from the previous
+              response to fetch the next page. When set, paging continues from this cursor and
+              since is ignored, while until still bounds the page. It is not an event's seq
+              field, so do not derive it from the response body.
+
+          since: Start of the window: an RFC-3339 timestamp, or a duration like 5m meaning that
+              long ago. Defaults to 5m. Ignored when offset is set.
+
+          until: End of the window (exclusive): an RFC-3339 timestamp, or a duration like 5m
+              meaning that long ago.
+
+          extra_headers: Send extra headers
+
+          extra_query: Add additional query parameters to the request
+
+          extra_body: Add additional JSON properties to the request
+
+          timeout: Override the client-level default timeout for this request, in seconds
+        """
+        if not id:
+            raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
+        return self._get_api_list(
+            path_template("/browsers/{id}/telemetry/events", id=id),
+            page=AsyncOffsetPagination[TelemetryEventsResponse],
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                query=maybe_transform(
+                    {
+                        "category": category,
+                        "limit": limit,
+                        "offset": offset,
+                        "since": since,
+                        "until": until,
+                    },
+                    telemetry_events_params.TelemetryEventsParams,
+                ),
+            ),
+            model=TelemetryEventsResponse,
+        )
+
     async def stream(
         self,
         id: str,
@@ -184,6 +359,9 @@ class TelemetryResourceWithRawResponse:
     def __init__(self, telemetry: TelemetryResource) -> None:
         self._telemetry = telemetry
 
+        self.events = to_raw_response_wrapper(
+            telemetry.events,
+        )
         self.stream = to_raw_response_wrapper(
             telemetry.stream,
         )
@@ -193,6 +371,9 @@ class AsyncTelemetryResourceWithRawResponse:
     def __init__(self, telemetry: AsyncTelemetryResource) -> None:
         self._telemetry = telemetry
 
+        self.events = async_to_raw_response_wrapper(
+            telemetry.events,
+        )
         self.stream = async_to_raw_response_wrapper(
             telemetry.stream,
         )
@@ -202,6 +383,9 @@ class TelemetryResourceWithStreamingResponse:
     def __init__(self, telemetry: TelemetryResource) -> None:
         self._telemetry = telemetry
 
+        self.events = to_streamed_response_wrapper(
+            telemetry.events,
+        )
         self.stream = to_streamed_response_wrapper(
             telemetry.stream,
         )
@@ -211,6 +395,9 @@ class AsyncTelemetryResourceWithStreamingResponse:
     def __init__(self, telemetry: AsyncTelemetryResource) -> None:
         self._telemetry = telemetry
 
+        self.events = async_to_streamed_response_wrapper(
+            telemetry.events,
+        )
         self.stream = async_to_streamed_response_wrapper(
             telemetry.stream,
         )
diff --git a/src/kernel/types/__init__.py b/src/kernel/types/__init__.py
@@ -111,9 +111,11 @@
     browsers.browser_call_stack.BrowserCallStack.update_forward_refs()  # type: ignore
     browsers.browser_console_error_event.BrowserConsoleErrorEvent.update_forward_refs()  # type: ignore
     browsers.browser_console_log_event.BrowserConsoleLogEvent.update_forward_refs()  # type: ignore
+    browsers.telemetry_events_response.TelemetryEventsResponse.update_forward_refs()  # type: ignore
     browsers.telemetry_stream_response.TelemetryStreamResponse.update_forward_refs()  # type: ignore
 else:
     browsers.browser_call_stack.BrowserCallStack.model_rebuild(_parent_namespace_depth=0)
     browsers.browser_console_error_event.BrowserConsoleErrorEvent.model_rebuild(_parent_namespace_depth=0)
     browsers.browser_console_log_event.BrowserConsoleLogEvent.model_rebuild(_parent_namespace_depth=0)
+    browsers.telemetry_events_response.TelemetryEventsResponse.model_rebuild(_parent_namespace_depth=0)
     browsers.telemetry_stream_response.TelemetryStreamResponse.model_rebuild(_parent_namespace_depth=0)
diff --git a/src/kernel/types/browsers/__init__.py b/src/kernel/types/browsers/__init__.py
@@ -37,6 +37,7 @@
 from .browser_telemetry_event import BrowserTelemetryEvent as BrowserTelemetryEvent
 from .process_resize_response import ProcessResizeResponse as ProcessResizeResponse
 from .process_status_response import ProcessStatusResponse as ProcessStatusResponse
+from .telemetry_events_params import TelemetryEventsParams as TelemetryEventsParams
 from .telemetry_stream_params import TelemetryStreamParams as TelemetryStreamParams
 from .browser_telemetry_config import BrowserTelemetryConfig as BrowserTelemetryConfig
 from .browser_cdp_connect_event import BrowserCdpConnectEvent as BrowserCdpConnectEvent
@@ -47,6 +48,7 @@
 from .f_delete_directory_params import FDeleteDirectoryParams as FDeleteDirectoryParams
 from .f_download_dir_zip_params import FDownloadDirZipParams as FDownloadDirZipParams
 from .playwright_execute_params import PlaywrightExecuteParams as PlaywrightExecuteParams
+from .telemetry_events_response import TelemetryEventsResponse as TelemetryEventsResponse
 from .telemetry_stream_response import TelemetryStreamResponse as TelemetryStreamResponse
 from .browser_network_idle_event import BrowserNetworkIdleEvent as BrowserNetworkIdleEvent
 from .computer_drag_mouse_params import ComputerDragMouseParams as ComputerDragMouseParams
diff --git a/src/kernel/types/browsers/telemetry_events_params.py b/src/kernel/types/browsers/telemetry_events_params.py
@@ -0,0 +1,52 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing import List
+from typing_extensions import Literal, TypedDict
+
+__all__ = ["TelemetryEventsParams"]
+
+
+class TelemetryEventsParams(TypedDict, total=False):
+    category: List[
+        Literal[
+            "console",
+            "network",
+            "page",
+            "interaction",
+            "control",
+            "connection",
+            "system",
+            "screenshot",
+            "captcha",
+            "monitor",
+        ]
+    ]
+    """Restrict results to these event categories.
+
+    Repeat the parameter for multiple values.
+    """
+
+    limit: int
+    """Maximum number of events per page. Defaults to 20."""
+
+    offset: int
+    """
+    Opaque pagination cursor: pass the X-Next-Offset value from the previous
+    response to fetch the next page. When set, paging continues from this cursor and
+    since is ignored, while until still bounds the page. It is not an event's seq
+    field, so do not derive it from the response body.
+    """
+
+    since: str
+    """
+    Start of the window: an RFC-3339 timestamp, or a duration like 5m meaning that
+    long ago. Defaults to 5m. Ignored when offset is set.
+    """
+
+    until: str
+    """
+    End of the window (exclusive): an RFC-3339 timestamp, or a duration like 5m
+    meaning that long ago.
+    """
diff --git a/src/kernel/types/browsers/telemetry_events_response.py b/src/kernel/types/browsers/telemetry_events_response.py
@@ -0,0 +1,36 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from ..._models import BaseModel
+
+__all__ = ["TelemetryEventsResponse"]
+
+
+class TelemetryEventsResponse(BaseModel):
+    """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.
+    """
+
+    event: "BrowserTelemetryEvent"
+    """Union type representing any browser telemetry event.
+
+    Discriminated on `type`. Each event's `category` determines when it is captured.
+    The CDP collector-health events (monitor_disconnected, monitor_reconnected,
+    monitor_reconnect_failed, monitor_init_failed) use the `monitor` category, which
+    is not user-configurable: it flows automatically whenever any CDP category
+    (console, network, page, interaction) is captured, and is silent otherwise.
+    monitor_screenshot uses the opt-in `screenshot` category. All other event types
+    are controlled by their per-category enable/disable flags.
+    """
+
+    seq: int
+    """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.
+    """
+
+
+from .browser_telemetry_event import BrowserTelemetryEvent
diff --git a/tests/api_resources/browsers/test_telemetry.py b/tests/api_resources/browsers/test_telemetry.py
