docs(openapi): describe unified concurrency limit, deprecate max_pooled_sessions (CUS-275)

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 125
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-ba32039d3975da7aa6d28e5184f0a44c9fbfe36ab7dbc71985d14e2ecc0867b9.yml
-openapi_spec_hash: a9f32fc90c2add2ae85af828c298e35b
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel/kernel-db45aab5b114bc0848eab997c85bfc02a653be9f929f8d090ec24187462733ee.yml
+openapi_spec_hash: 82f4282312699f8d54bec207e981efe8
 config_hash: 06186eb40e0058a2a87ac251fc07415d

src/kernel/resources/organization/limits.py

@@ -56,8 +56,9 @@ def retrieve(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> OrgLimits:
         """
-        Get the organization's concurrent session ceiling and the default per-project
-        concurrency cap applied to projects without an explicit override.
+        Get the organization's concurrency limit — the maximum browsers running at once
+        across on-demand sessions and browser pool reservations — and the default
+        per-project concurrency cap applied to projects without an explicit override.
         """
         return self._get(
             "/org/limits",
@@ -81,13 +82,12 @@ def update(
         """
         Set the default per-project concurrency cap applied to projects without an
         explicit override. Set the value to 0 to remove the default; omit to leave it
-        unchanged. The default cannot exceed the organization's concurrent session
-        ceiling.
+        unchanged. The default cannot exceed the organization's concurrency limit.
 
         Args:
-          default_project_max_concurrent_sessions: Default maximum concurrent browser sessions for projects without an explicit
-              override. Set to 0 to remove the default; omit to leave unchanged. Cannot exceed
-              the organization's concurrent session ceiling.
+          default_project_max_concurrent_sessions: Default maximum concurrent browsers for projects without an explicit override.
+              Set to 0 to remove the default; omit to leave unchanged. Cannot exceed the
+              organization's concurrency limit.
 
           extra_headers: Send extra headers
 
@@ -143,8 +143,9 @@ async def retrieve(
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> OrgLimits:
         """
-        Get the organization's concurrent session ceiling and the default per-project
-        concurrency cap applied to projects without an explicit override.
+        Get the organization's concurrency limit — the maximum browsers running at once
+        across on-demand sessions and browser pool reservations — and the default
+        per-project concurrency cap applied to projects without an explicit override.
         """
         return await self._get(
             "/org/limits",
@@ -168,13 +169,12 @@ async def update(
         """
         Set the default per-project concurrency cap applied to projects without an
         explicit override. Set the value to 0 to remove the default; omit to leave it
-        unchanged. The default cannot exceed the organization's concurrent session
-        ceiling.
+        unchanged. The default cannot exceed the organization's concurrency limit.
 
         Args:
-          default_project_max_concurrent_sessions: Default maximum concurrent browser sessions for projects without an explicit
-              override. Set to 0 to remove the default; omit to leave unchanged. Cannot exceed
-              the organization's concurrent session ceiling.
+          default_project_max_concurrent_sessions: Default maximum concurrent browsers for projects without an explicit override.
+              Set to 0 to remove the default; omit to leave unchanged. Cannot exceed the
+              organization's concurrency limit.
 
           extra_headers: Send extra headers
 

src/kernel/resources/projects/limits.py

@@ -104,11 +104,13 @@ def update(
           max_concurrent_invocations: Maximum concurrent app invocations for this project. Set to 0 to remove the cap;
               omit to leave unchanged.
 
-          max_concurrent_sessions: Maximum concurrent browser sessions for this project. Set to 0 to remove the
-              cap; omit to leave unchanged.
+          max_concurrent_sessions: Maximum concurrent browsers for this project, covering both on-demand sessions
+              and browser pool reservations. Set to 0 to remove the cap; omit to leave
+              unchanged.
 
-          max_pooled_sessions: Maximum pooled sessions capacity for this project. Set to 0 to remove the cap;
-              omit to leave unchanged.
+          max_pooled_sessions: Deprecated: pooled browsers now count toward `max_concurrent_sessions`. Requests
+              that set this field are rejected with a 400 once the unified concurrency limit
+              is enabled for your organization.
 
           extra_headers: Send extra headers
 
@@ -218,11 +220,13 @@ async def update(
           max_concurrent_invocations: Maximum concurrent app invocations for this project. Set to 0 to remove the cap;
               omit to leave unchanged.
 
-          max_concurrent_sessions: Maximum concurrent browser sessions for this project. Set to 0 to remove the
-              cap; omit to leave unchanged.
+          max_concurrent_sessions: Maximum concurrent browsers for this project, covering both on-demand sessions
+              and browser pool reservations. Set to 0 to remove the cap; omit to leave
+              unchanged.
 
-          max_pooled_sessions: Maximum pooled sessions capacity for this project. Set to 0 to remove the cap;
-              omit to leave unchanged.
+          max_pooled_sessions: Deprecated: pooled browsers now count toward `max_concurrent_sessions`. Requests
+              that set this field are rejected with a 400 once the unified concurrency limit
+              is enabled for your organization.
 
           extra_headers: Send extra headers
 

src/kernel/types/organization/limit_update_params.py

@@ -10,8 +10,8 @@
 
 class LimitUpdateParams(TypedDict, total=False):
     default_project_max_concurrent_sessions: Optional[int]
-    """
-    Default maximum concurrent browser sessions for projects without an explicit
-    override. Set to 0 to remove the default; omit to leave unchanged. Cannot exceed
-    the organization's concurrent session ceiling.
+    """Default maximum concurrent browsers for projects without an explicit override.
+
+    Set to 0 to remove the default; omit to leave unchanged. Cannot exceed the
+    organization's concurrency limit.
     """

src/kernel/types/organization/org_limits.py

@@ -10,15 +10,16 @@
 class OrgLimits(BaseModel):
     default_project_max_concurrent_sessions: Optional[int] = None
     """
-    Default maximum concurrent browser sessions applied to every project that has no
+    Default maximum concurrent browsers applied to every project that has no
     explicit per-project override. Null means no org-level default, so such projects
     are uncapped (only the org-wide limit applies). Applies to existing and newly
     created projects.
     """
 
     max_concurrent_sessions: Optional[int] = None
     """
-    The organization's effective concurrent browser session ceiling, from its plan
-    or an override. Read-only and shared across all projects in the org; a
+    The organization's effective concurrency limit — the maximum browsers running at
+    once, covering both on-demand sessions and browser pool reservations — from its
+    plan or an override. Read-only and shared across all projects in the org; a
     per-project default cannot exceed it.
     """

src/kernel/types/projects/limit_update_params.py

@@ -16,13 +16,15 @@ class LimitUpdateParams(TypedDict, total=False):
     """
 
     max_concurrent_sessions: Optional[int]
-    """Maximum concurrent browser sessions for this project.
-
-    Set to 0 to remove the cap; omit to leave unchanged.
+    """
+    Maximum concurrent browsers for this project, covering both on-demand sessions
+    and browser pool reservations. Set to 0 to remove the cap; omit to leave
+    unchanged.
     """
 
     max_pooled_sessions: Optional[int]
-    """Maximum pooled sessions capacity for this project.
+    """Deprecated: pooled browsers now count toward `max_concurrent_sessions`.
 
-    Set to 0 to remove the cap; omit to leave unchanged.
+    Requests that set this field are rejected with a 400 once the unified
+    concurrency limit is enabled for your organization.
     """

src/kernel/types/projects/project_limits.py

@@ -15,13 +15,14 @@ class ProjectLimits(BaseModel):
     """
 
     max_concurrent_sessions: Optional[int] = None
-    """Maximum concurrent browser sessions for this project.
-
-    Null means no project-level cap.
+    """
+    Maximum concurrent browsers for this project, covering both on-demand sessions
+    (`browsers.create()`) and browser pool reservations. Null means no project-level
+    cap.
     """
 
     max_pooled_sessions: Optional[int] = None
-    """Maximum pooled sessions capacity for this project.
+    """Deprecated: pooled browsers now count toward `max_concurrent_sessions`.
 
-    Null means no project-level cap.
+    Always null once the unified concurrency limit is enabled for your organization.
     """