feat: Add region as a first-class API field with plan and flag gating

Stainless-Generated-From: 91d0b1968ff1d553bd8eb0700df9b6c8d9167bce

Author: kernel-internal[bot]

src/kernel/resources/browser_pools.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from typing import Dict, Iterable, Optional
+from typing_extensions import Literal
 
 import httpx
 
@@ -70,6 +71,7 @@ def create(
         profile: browser_pool_create_params.Profile | Omit = omit,
         proxy_id: str | Omit = omit,
         refresh_on_profile_update: bool | Omit = omit,
+        region: Literal["us-east", "eu-west"] | Omit = omit,
         start_url: str | Omit = omit,
         stealth: bool | Omit = omit,
         telemetry: Optional[browser_pool_create_params.Telemetry] | Omit = omit,
@@ -126,6 +128,10 @@ def create(
               pool browsers pick up the latest profile data. When a profile is provided during
               creation, this defaults to true. Requires a profile to be set on the pool.
 
+          region: Geographic region for the browser pool. It is fixed once the pool is created.
+              Region selection requires a Start-Up or Enterprise plan, defaults to us-east
+              when omitted on create.
+
           start_url: Optional URL to navigate to when a new browser is warmed into the pool.
               Best-effort: failures to navigate do not fail pool fill. Only applied to
               newly-warmed browsers; browsers reused via release/acquire keep whatever URL the
@@ -180,6 +186,7 @@ def create(
                     "profile": profile,
                     "proxy_id": proxy_id,
                     "refresh_on_profile_update": refresh_on_profile_update,
+                    "region": region,
                     "start_url": start_url,
                     "stealth": stealth,
                     "telemetry": telemetry,
@@ -386,6 +393,7 @@ def list(
         name: str | Omit = omit,
         offset: int | Omit = omit,
         query: str | Omit = omit,
+        region: Literal["us-east", "eu-west"] | 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,
@@ -409,6 +417,8 @@ def list(
           query: Case-insensitive substring match against browser pool name. IDs match by exact
               value.
 
+          region: Filter pools by geographic region. Omit to list pools in all regions.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -431,6 +441,7 @@ def list(
                         "name": name,
                         "offset": offset,
                         "query": query,
+                        "region": region,
                     },
                     browser_pool_list_params.BrowserPoolListParams,
                 ),
@@ -678,6 +689,7 @@ async def create(
         profile: browser_pool_create_params.Profile | Omit = omit,
         proxy_id: str | Omit = omit,
         refresh_on_profile_update: bool | Omit = omit,
+        region: Literal["us-east", "eu-west"] | Omit = omit,
         start_url: str | Omit = omit,
         stealth: bool | Omit = omit,
         telemetry: Optional[browser_pool_create_params.Telemetry] | Omit = omit,
@@ -734,6 +746,10 @@ async def create(
               pool browsers pick up the latest profile data. When a profile is provided during
               creation, this defaults to true. Requires a profile to be set on the pool.
 
+          region: Geographic region for the browser pool. It is fixed once the pool is created.
+              Region selection requires a Start-Up or Enterprise plan, defaults to us-east
+              when omitted on create.
+
           start_url: Optional URL to navigate to when a new browser is warmed into the pool.
               Best-effort: failures to navigate do not fail pool fill. Only applied to
               newly-warmed browsers; browsers reused via release/acquire keep whatever URL the
@@ -788,6 +804,7 @@ async def create(
                     "profile": profile,
                     "proxy_id": proxy_id,
                     "refresh_on_profile_update": refresh_on_profile_update,
+                    "region": region,
                     "start_url": start_url,
                     "stealth": stealth,
                     "telemetry": telemetry,
@@ -994,6 +1011,7 @@ def list(
         name: str | Omit = omit,
         offset: int | Omit = omit,
         query: str | Omit = omit,
+        region: Literal["us-east", "eu-west"] | 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,
@@ -1017,6 +1035,8 @@ def list(
           query: Case-insensitive substring match against browser pool name. IDs match by exact
               value.
 
+          region: Filter pools by geographic region. Omit to list pools in all regions.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -1039,6 +1059,7 @@ def list(
                         "name": name,
                         "offset": offset,
                         "query": query,
+                        "region": region,
                     },
                     browser_pool_list_params.BrowserPoolListParams,
                 ),

src/kernel/resources/browsers/browsers.py

@@ -175,6 +175,7 @@ def create(
         profile: BrowserProfile | Omit = omit,
         proxy: BrowserProxyConfigParam | Omit = omit,
         proxy_id: str | Omit = omit,
+        region: Literal["us-east", "eu-west"] | Omit = omit,
         start_url: str | Omit = omit,
         stealth: bool | Omit = omit,
         tags: TagsParam | Omit = omit,
@@ -229,6 +230,10 @@ def create(
           proxy_id: Optional proxy to associate to the browser session. Must reference a proxy in
               the same project as the browser session. Deprecated in favor of proxy.
 
+          region: Geographic region for the browser session. It is fixed once the session is
+              created. Region selection requires a Start-Up or Enterprise plan, defaults to
+              us-east when omitted on create.
+
           start_url: Optional URL to open when the browser session is created. Navigation is
               best-effort, so navigation failures do not prevent the session from being
               created.
@@ -290,6 +295,7 @@ def create(
                     "profile": profile,
                     "proxy": proxy,
                     "proxy_id": proxy_id,
+                    "region": region,
                     "start_url": start_url,
                     "stealth": stealth,
                     "tags": tags,
@@ -440,6 +446,7 @@ def list(
         limit: int | Omit = omit,
         offset: int | Omit = omit,
         query: str | Omit = omit,
+        region: Literal["us-east", "eu-west"] | Omit = omit,
         status: Literal["active", "deleted", "all"] | Omit = omit,
         tags: Dict[str, str] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
@@ -464,6 +471,8 @@ def list(
 
           query: Search browsers by name, session ID, profile name or ID, proxy ID, or pool name.
 
+          region: Filter sessions by geographic region. Omit to list sessions in all regions.
+
           status: Filter sessions by status. "active" returns only active sessions (default),
               "deleted" returns only soft-deleted sessions, "all" returns both.
 
@@ -493,6 +502,7 @@ def list(
                         "limit": limit,
                         "offset": offset,
                         "query": query,
+                        "region": region,
                         "status": status,
                         "tags": tags,
                     },
@@ -775,6 +785,7 @@ async def create(
         profile: BrowserProfile | Omit = omit,
         proxy: BrowserProxyConfigParam | Omit = omit,
         proxy_id: str | Omit = omit,
+        region: Literal["us-east", "eu-west"] | Omit = omit,
         start_url: str | Omit = omit,
         stealth: bool | Omit = omit,
         tags: TagsParam | Omit = omit,
@@ -829,6 +840,10 @@ async def create(
           proxy_id: Optional proxy to associate to the browser session. Must reference a proxy in
               the same project as the browser session. Deprecated in favor of proxy.
 
+          region: Geographic region for the browser session. It is fixed once the session is
+              created. Region selection requires a Start-Up or Enterprise plan, defaults to
+              us-east when omitted on create.
+
           start_url: Optional URL to open when the browser session is created. Navigation is
               best-effort, so navigation failures do not prevent the session from being
               created.
@@ -890,6 +905,7 @@ async def create(
                     "profile": profile,
                     "proxy": proxy,
                     "proxy_id": proxy_id,
+                    "region": region,
                     "start_url": start_url,
                     "stealth": stealth,
                     "tags": tags,
@@ -1040,6 +1056,7 @@ def list(
         limit: int | Omit = omit,
         offset: int | Omit = omit,
         query: str | Omit = omit,
+        region: Literal["us-east", "eu-west"] | Omit = omit,
         status: Literal["active", "deleted", "all"] | Omit = omit,
         tags: Dict[str, str] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
@@ -1064,6 +1081,8 @@ def list(
 
           query: Search browsers by name, session ID, profile name or ID, proxy ID, or pool name.
 
+          region: Filter sessions by geographic region. Omit to list sessions in all regions.
+
           status: Filter sessions by status. "active" returns only active sessions (default),
               "deleted" returns only soft-deleted sessions, "all" returns both.
 
@@ -1093,6 +1112,7 @@ def list(
                         "limit": limit,
                         "offset": offset,
                         "query": query,
+                        "region": region,
                         "status": status,
                         "tags": tags,
                     },

src/kernel/types/browser_create_params.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from typing import Dict, Iterable, Optional
-from typing_extensions import TypedDict
+from typing_extensions import Literal, TypedDict
 
 from .tags_param import TagsParam
 from .browser_proxy_config_param import BrowserProxyConfigParam
@@ -90,6 +90,13 @@ class BrowserCreateParams(TypedDict, total=False):
     favor of proxy.
     """
 
+    region: Literal["us-east", "eu-west"]
+    """Geographic region for the browser session.
+
+    It is fixed once the session is created. Region selection requires a Start-Up or
+    Enterprise plan, defaults to us-east when omitted on create.
+    """
+
     start_url: str
     """Optional URL to open when the browser session is created.
 

src/kernel/types/browser_create_response.py

@@ -2,6 +2,7 @@
 
 from typing import Dict, Optional
 from datetime import datetime
+from typing_extensions import Literal
 
 from .tags import Tags
 from .profile import Profile
@@ -25,6 +26,9 @@ class BrowserCreateResponse(BaseModel):
     headless: bool
     """Whether the browser session is running in headless mode."""
 
+    region: Literal["us-east", "eu-west"]
+    """Geographic region of the browser session. Fixed once the session is created."""
+
     session_id: str
     """Unique identifier for the browser session"""
 

src/kernel/types/browser_list_params.py

@@ -27,6 +27,9 @@ class BrowserListParams(TypedDict, total=False):
     Search browsers by name, session ID, profile name or ID, proxy ID, or pool name.
     """
 
+    region: Literal["us-east", "eu-west"]
+    """Filter sessions by geographic region. Omit to list sessions in all regions."""
+
     status: Literal["active", "deleted", "all"]
     """Filter sessions by status.
 

src/kernel/types/browser_list_response.py

@@ -2,6 +2,7 @@
 
 from typing import Dict, Optional
 from datetime import datetime
+from typing_extensions import Literal
 
 from .tags import Tags
 from .profile import Profile
@@ -25,6 +26,9 @@ class BrowserListResponse(BaseModel):
     headless: bool
     """Whether the browser session is running in headless mode."""
 
+    region: Literal["us-east", "eu-west"]
+    """Geographic region of the browser session. Fixed once the session is created."""
+
     session_id: str
     """Unique identifier for the browser session"""
 

src/kernel/types/browser_pool.py

@@ -2,6 +2,7 @@
 
 from typing import Dict, List, Optional
 from datetime import datetime
+from typing_extensions import Literal
 
 from .._models import BaseModel
 from .shared.browser_viewport import BrowserViewport
@@ -166,6 +167,9 @@ class BrowserPool(BaseModel):
     (echoed as sent on create).
     """
 
+    region: Literal["us-east", "eu-west"]
+    """Geographic region of the browser pool. Fixed once the pool is created."""
+
     name: Optional[str] = None
     """Browser pool name, if set"""
 

src/kernel/types/browser_pool_acquire_response.py

@@ -2,6 +2,7 @@
 
 from typing import Dict, Optional
 from datetime import datetime
+from typing_extensions import Literal
 
 from .tags import Tags
 from .profile import Profile
@@ -25,6 +26,9 @@ class BrowserPoolAcquireResponse(BaseModel):
     headless: bool
     """Whether the browser session is running in headless mode."""
 
+    region: Literal["us-east", "eu-west"]
+    """Geographic region of the browser session. Fixed once the session is created."""
+
     session_id: str
     """Unique identifier for the browser session"""
 

src/kernel/types/browser_pool_create_params.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from typing import Dict, Iterable, Optional
-from typing_extensions import Required, TypedDict
+from typing_extensions import Literal, Required, TypedDict
 
 from .shared_params.browser_viewport import BrowserViewport
 from .shared_params.browser_extension import BrowserExtension
@@ -83,6 +83,13 @@ class BrowserPoolCreateParams(TypedDict, total=False):
     creation, this defaults to true. Requires a profile to be set on the pool.
     """
 
+    region: Literal["us-east", "eu-west"]
+    """Geographic region for the browser pool.
+
+    It is fixed once the pool is created. Region selection requires a Start-Up or
+    Enterprise plan, defaults to us-east when omitted on create.
+    """
+
     start_url: str
     """Optional URL to navigate to when a new browser is warmed into the pool.
 

src/kernel/types/browser_pool_list_params.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing_extensions import TypedDict
+from typing_extensions import Literal, TypedDict
 
 __all__ = ["BrowserPoolListParams"]
 
@@ -27,3 +27,6 @@ class BrowserPoolListParams(TypedDict, total=False):
 
     IDs match by exact value.
     """
+
+    region: Literal["us-east", "eu-west"]
+    """Filter pools by geographic region. Omit to list pools in all regions."""