feat: Add telemetry support for browser pools with BAA enforcement

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 127
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-92c776855f978ae03a778fbbac49bf1edc65852530644772c382838b6eab9fe5.yml
-openapi_spec_hash: 4a9fbcb607be408ad646e207fe90687f
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-e04362b2c82b88f4f7fb43209c764fa9fdf37fe98932e142547be43a1e99c50b.yml
+openapi_spec_hash: b16e79bfd6cac36090c815a8184b9e09
 config_hash: 77ee715aa17061166f9a02b264a21b8d

src/kernel/resources/browser_pools.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Dict, Iterable
+from typing import Dict, Iterable, Optional
 
 import httpx
 
@@ -72,6 +72,7 @@ def create(
         refresh_on_profile_update: bool | Omit = omit,
         start_url: str | Omit = omit,
         stealth: bool | Omit = omit,
+        telemetry: Optional[browser_pool_create_params.Telemetry] | Omit = omit,
         timeout_seconds: int | Omit = omit,
         viewport: BrowserViewport | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
@@ -134,6 +135,13 @@ def create(
           stealth: If true, launches the browser in stealth mode to reduce detection by anti-bot
               mechanisms. Defaults to false.
 
+          telemetry: Telemetry configuration applied to browsers warmed into this pool. Set enabled
+              to true to start capture using the default set, or provide browser category
+              settings. If omitted, null, set to an empty object ({}), set to enabled: false
+              without browser category settings, or all four CDP categories are explicitly
+              disabled, no telemetry is configured on the pool. Only applied to newly-warmed
+              browsers.
+
           timeout_seconds: Default idle timeout in seconds for browsers acquired from this pool before they
               are destroyed. Defaults to 600 seconds. Minimum 10, maximum 259200 (72 hours).
 
@@ -174,6 +182,7 @@ def create(
                     "refresh_on_profile_update": refresh_on_profile_update,
                     "start_url": start_url,
                     "stealth": stealth,
+                    "telemetry": telemetry,
                     "timeout_seconds": timeout_seconds,
                     "viewport": viewport,
                 },
@@ -235,6 +244,7 @@ def update(
         size: int | Omit = omit,
         start_url: str | Omit = omit,
         stealth: bool | Omit = omit,
+        telemetry: Optional[browser_pool_update_params.Telemetry] | Omit = omit,
         timeout_seconds: int | Omit = omit,
         viewport: BrowserViewport | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
@@ -306,6 +316,14 @@ def update(
 
           stealth: If provided, replaces whether browsers launch in stealth mode.
 
+          telemetry: If provided, updates the pool's telemetry configuration. Omit, set to null, or
+              set to an empty object ({}) to leave the existing configuration unchanged. Set
+              enabled to true to enable capture using the default set. Set enabled to false to
+              clear the pool's telemetry. Provide browser category settings for per-category
+              updates, merged onto the pool's current configuration. Only applied to browsers
+              warmed after the update; browsers already in the pool keep their configuration
+              until discarded.
+
           timeout_seconds: If provided, replaces the default idle timeout in seconds for browsers acquired
               from this pool before they are destroyed. Minimum 10, maximum 259200 (72 hours).
 
@@ -349,6 +367,7 @@ def update(
                     "size": size,
                     "start_url": start_url,
                     "stealth": stealth,
+                    "telemetry": telemetry,
                     "timeout_seconds": timeout_seconds,
                     "viewport": viewport,
                 },
@@ -468,6 +487,7 @@ def acquire(
         name: str | Omit = omit,
         start_url: str | Omit = omit,
         tags: TagsParam | Omit = omit,
+        telemetry: Optional[browser_pool_acquire_params.Telemetry] | 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,
@@ -500,6 +520,15 @@ def acquire(
               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: 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.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -518,6 +547,7 @@ def acquire(
                     "name": name,
                     "start_url": start_url,
                     "tags": tags,
+                    "telemetry": telemetry,
                 },
                 browser_pool_acquire_params.BrowserPoolAcquireParams,
             ),
@@ -650,6 +680,7 @@ async def create(
         refresh_on_profile_update: bool | Omit = omit,
         start_url: str | Omit = omit,
         stealth: bool | Omit = omit,
+        telemetry: Optional[browser_pool_create_params.Telemetry] | Omit = omit,
         timeout_seconds: int | Omit = omit,
         viewport: BrowserViewport | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
@@ -712,6 +743,13 @@ async def create(
           stealth: If true, launches the browser in stealth mode to reduce detection by anti-bot
               mechanisms. Defaults to false.
 
+          telemetry: Telemetry configuration applied to browsers warmed into this pool. Set enabled
+              to true to start capture using the default set, or provide browser category
+              settings. If omitted, null, set to an empty object ({}), set to enabled: false
+              without browser category settings, or all four CDP categories are explicitly
+              disabled, no telemetry is configured on the pool. Only applied to newly-warmed
+              browsers.
+
           timeout_seconds: Default idle timeout in seconds for browsers acquired from this pool before they
               are destroyed. Defaults to 600 seconds. Minimum 10, maximum 259200 (72 hours).
 
@@ -752,6 +790,7 @@ async def create(
                     "refresh_on_profile_update": refresh_on_profile_update,
                     "start_url": start_url,
                     "stealth": stealth,
+                    "telemetry": telemetry,
                     "timeout_seconds": timeout_seconds,
                     "viewport": viewport,
                 },
@@ -813,6 +852,7 @@ async def update(
         size: int | Omit = omit,
         start_url: str | Omit = omit,
         stealth: bool | Omit = omit,
+        telemetry: Optional[browser_pool_update_params.Telemetry] | Omit = omit,
         timeout_seconds: int | Omit = omit,
         viewport: BrowserViewport | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
@@ -884,6 +924,14 @@ async def update(
 
           stealth: If provided, replaces whether browsers launch in stealth mode.
 
+          telemetry: If provided, updates the pool's telemetry configuration. Omit, set to null, or
+              set to an empty object ({}) to leave the existing configuration unchanged. Set
+              enabled to true to enable capture using the default set. Set enabled to false to
+              clear the pool's telemetry. Provide browser category settings for per-category
+              updates, merged onto the pool's current configuration. Only applied to browsers
+              warmed after the update; browsers already in the pool keep their configuration
+              until discarded.
+
           timeout_seconds: If provided, replaces the default idle timeout in seconds for browsers acquired
               from this pool before they are destroyed. Minimum 10, maximum 259200 (72 hours).
 
@@ -927,6 +975,7 @@ async def update(
                     "size": size,
                     "start_url": start_url,
                     "stealth": stealth,
+                    "telemetry": telemetry,
                     "timeout_seconds": timeout_seconds,
                     "viewport": viewport,
                 },
@@ -1046,6 +1095,7 @@ async def acquire(
         name: str | Omit = omit,
         start_url: str | Omit = omit,
         tags: TagsParam | Omit = omit,
+        telemetry: Optional[browser_pool_acquire_params.Telemetry] | 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,
@@ -1078,6 +1128,15 @@ async def acquire(
               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: 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.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -1096,6 +1155,7 @@ async def acquire(
                     "name": name,
                     "start_url": start_url,
                     "tags": tags,
+                    "telemetry": telemetry,
                 },
                 browser_pool_acquire_params.BrowserPoolAcquireParams,
             ),

src/kernel/types/browser_pool.py

@@ -6,6 +6,7 @@
 from .._models import BaseModel
 from .shared.browser_viewport import BrowserViewport
 from .shared.browser_extension import BrowserExtension
+from .browsers.browser_telemetry_config import BrowserTelemetryConfig
 
 __all__ = ["BrowserPool", "BrowserPoolConfig", "BrowserPoolConfigProfile"]
 
@@ -110,6 +111,12 @@ class BrowserPoolConfig(BaseModel):
     mechanisms.
     """
 
+    telemetry: Optional[BrowserTelemetryConfig] = None
+    """
+    Active telemetry configuration applied to browsers warmed into this pool, if
+    any.
+    """
+
     timeout_seconds: Optional[int] = None
     """
     Default idle timeout in seconds for browsers acquired from this pool before they

src/kernel/types/browser_pool_acquire_params.py

@@ -2,11 +2,13 @@
 
 from __future__ import annotations
 
+from typing import Optional
 from typing_extensions import TypedDict
 
 from .tags_param import TagsParam
+from .browsers.browser_telemetry_categories_config_param import BrowserTelemetryCategoriesConfigParam
 
-__all__ = ["BrowserPoolAcquireParams"]
+__all__ = ["BrowserPoolAcquireParams", "Telemetry"]
 
 
 class BrowserPoolAcquireParams(TypedDict, total=False):
@@ -38,3 +40,49 @@ class BrowserPoolAcquireParams(TypedDict, total=False):
     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: Optional[Telemetry]
+    """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.
+    """
+
+
+class Telemetry(TypedDict, total=False):
+    """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.
+    """
+
+    browser: BrowserTelemetryCategoriesConfigParam
+    """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: bool
+    """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.
+    """

src/kernel/types/browser_pool_create_params.py

@@ -2,13 +2,14 @@
 
 from __future__ import annotations
 
-from typing import Dict, Iterable
+from typing import Dict, Iterable, Optional
 from typing_extensions import Required, TypedDict
 
 from .shared_params.browser_viewport import BrowserViewport
 from .shared_params.browser_extension import BrowserExtension
+from .browsers.browser_telemetry_categories_config_param import BrowserTelemetryCategoriesConfigParam
 
-__all__ = ["BrowserPoolCreateParams", "Profile"]
+__all__ = ["BrowserPoolCreateParams", "Profile", "Telemetry"]
 
 
 class BrowserPoolCreateParams(TypedDict, total=False):
@@ -90,6 +91,16 @@ class BrowserPoolCreateParams(TypedDict, total=False):
     mechanisms. Defaults to false.
     """
 
+    telemetry: Optional[Telemetry]
+    """Telemetry configuration applied to browsers warmed into this pool.
+
+    Set enabled to true to start capture using the default set, or provide browser
+    category settings. If omitted, null, set to an empty object ({}), set to
+    enabled: false without browser category settings, or all four CDP categories are
+    explicitly disabled, no telemetry is configured on the pool. Only applied to
+    newly-warmed browsers.
+    """
+
     timeout_seconds: int
     """
     Default idle timeout in seconds for browsers acquired from this pool before they
@@ -130,3 +141,37 @@ class Profile(TypedDict, total=False):
 
     Must be 1-255 characters, using letters, numbers, dots, underscores, or hyphens.
     """
+
+
+class Telemetry(TypedDict, total=False):
+    """Telemetry configuration applied to browsers warmed into this pool.
+
+    Set enabled to true to start capture using the default set, or provide browser category settings. If omitted, null, set to an empty object ({}), set to enabled: false without browser category settings, or all four CDP categories are explicitly disabled, no telemetry is configured on the pool. Only applied to newly-warmed browsers.
+    """
+
+    browser: BrowserTelemetryCategoriesConfigParam
+    """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: bool
+    """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.
+    """