feat: Add optional url parameter to proxy check endpoint

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 104
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-403eadeddcd92ecf5c0ada739fb59d73d829a9b463788a81ac3ed97d0cd3a64b.yml
-openapi_spec_hash: 8fdd3a5bd5e035f0adeb72329c215ad7
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-f7024f4171c7c4ec558de1c27f338b1089ffddd0d2dbfdb9bb9f9c2abe8f47bf.yml
+openapi_spec_hash: ced43682b49e73a2862f99b49abb4fcd
 config_hash: 16e4457a0bb26e98a335a1c2a572290a

api.md

@@ -282,7 +282,7 @@ Methods:
 - <code title="get /proxies/{id}">client.proxies.<a href="./src/kernel/resources/proxies.py">retrieve</a>(id) -> <a href="./src/kernel/types/proxy_retrieve_response.py">ProxyRetrieveResponse</a></code>
 - <code title="get /proxies">client.proxies.<a href="./src/kernel/resources/proxies.py">list</a>() -> <a href="./src/kernel/types/proxy_list_response.py">ProxyListResponse</a></code>
 - <code title="delete /proxies/{id}">client.proxies.<a href="./src/kernel/resources/proxies.py">delete</a>(id) -> None</code>
-- <code title="post /proxies/{id}/check">client.proxies.<a href="./src/kernel/resources/proxies.py">check</a>(id) -> <a href="./src/kernel/types/proxy_check_response.py">ProxyCheckResponse</a></code>
+- <code title="post /proxies/{id}/check">client.proxies.<a href="./src/kernel/resources/proxies.py">check</a>(id, \*\*<a href="src/kernel/types/proxy_check_params.py">params</a>) -> <a href="./src/kernel/types/proxy_check_response.py">ProxyCheckResponse</a></code>
 
 # Extensions
 

src/kernel/resources/proxies.py

@@ -6,7 +6,7 @@
 
 import httpx
 
-from ..types import proxy_create_params
+from ..types import proxy_check_params, proxy_create_params
 from .._types import Body, Omit, Query, Headers, NoneType, NotGiven, SequenceNotStr, omit, not_given
 from .._utils import path_template, maybe_transform, async_maybe_transform
 from .._compat import cached_property
@@ -195,17 +195,35 @@ def check(
         self,
         id: str,
         *,
+        url: 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,
     ) -> ProxyCheckResponse:
-        """
-        Run a health check on the proxy to verify it's working.
+        """Run a health check on the proxy to verify it's working.
+
+        Optionally specify a URL
+        to test reachability against a specific target. For ISP and datacenter proxies,
+        this reliably tests whether the target site is reachable from the proxy's stable
+        exit IP. For residential and mobile proxies, the exit node varies between
+        requests, so this validates proxy configuration and connectivity rather than
+        guaranteeing site-specific reachability.
 
         Args:
+          url: An optional URL to test reachability against. If provided, the proxy check will
+              test connectivity to this URL instead of the default test URLs. Only HTTP and
+              HTTPS schemes are allowed, and the URL must resolve to a public IP address. For
+              ISP and datacenter proxies, the exit IP is stable, so a successful check
+              reliably indicates that subsequent browser sessions will reach the target site
+              with the same IP. For residential and mobile proxies, the exit node changes
+              between requests, so a successful check validates proxy configuration but does
+              not guarantee that a subsequent browser session will use the same exit IP or
+              reach the same site — it is useful for verifying credentials and connectivity,
+              not for predicting site-specific behavior.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -218,6 +236,7 @@ def check(
             raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
         return self._post(
             path_template("/proxies/{id}/check", id=id),
+            body=maybe_transform({"url": url}, proxy_check_params.ProxyCheckParams),
             options=make_request_options(
                 extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
             ),
@@ -394,17 +413,35 @@ async def check(
         self,
         id: str,
         *,
+        url: 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,
     ) -> ProxyCheckResponse:
-        """
-        Run a health check on the proxy to verify it's working.
+        """Run a health check on the proxy to verify it's working.
+
+        Optionally specify a URL
+        to test reachability against a specific target. For ISP and datacenter proxies,
+        this reliably tests whether the target site is reachable from the proxy's stable
+        exit IP. For residential and mobile proxies, the exit node varies between
+        requests, so this validates proxy configuration and connectivity rather than
+        guaranteeing site-specific reachability.
 
         Args:
+          url: An optional URL to test reachability against. If provided, the proxy check will
+              test connectivity to this URL instead of the default test URLs. Only HTTP and
+              HTTPS schemes are allowed, and the URL must resolve to a public IP address. For
+              ISP and datacenter proxies, the exit IP is stable, so a successful check
+              reliably indicates that subsequent browser sessions will reach the target site
+              with the same IP. For residential and mobile proxies, the exit node changes
+              between requests, so a successful check validates proxy configuration but does
+              not guarantee that a subsequent browser session will use the same exit IP or
+              reach the same site — it is useful for verifying credentials and connectivity,
+              not for predicting site-specific behavior.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -417,6 +454,7 @@ async def check(
             raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
         return await self._post(
             path_template("/proxies/{id}/check", id=id),
+            body=await async_maybe_transform({"url": url}, proxy_check_params.ProxyCheckParams),
             options=make_request_options(
                 extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
             ),

src/kernel/types/__init__.py

@@ -20,6 +20,7 @@
 from .app_list_params import AppListParams as AppListParams
 from .browser_pool_ref import BrowserPoolRef as BrowserPoolRef
 from .app_list_response import AppListResponse as AppListResponse
+from .proxy_check_params import ProxyCheckParams as ProxyCheckParams
 from .browser_list_params import BrowserListParams as BrowserListParams
 from .browser_persistence import BrowserPersistence as BrowserPersistence
 from .credential_provider import CredentialProvider as CredentialProvider

src/kernel/types/proxy_check_params.py

@@ -0,0 +1,23 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import TypedDict
+
+__all__ = ["ProxyCheckParams"]
+
+
+class ProxyCheckParams(TypedDict, total=False):
+    url: str
+    """An optional URL to test reachability against.
+
+    If provided, the proxy check will test connectivity to this URL instead of the
+    default test URLs. Only HTTP and HTTPS schemes are allowed, and the URL must
+    resolve to a public IP address. For ISP and datacenter proxies, the exit IP is
+    stable, so a successful check reliably indicates that subsequent browser
+    sessions will reach the target site with the same IP. For residential and mobile
+    proxies, the exit node changes between requests, so a successful check validates
+    proxy configuration but does not guarantee that a subsequent browser session
+    will use the same exit IP or reach the same site — it is useful for verifying
+    credentials and connectivity, not for predicting site-specific behavior.
+    """

tests/api_resources/test_proxies.py

@@ -184,15 +184,24 @@ def test_path_params_delete(self, client: Kernel) -> None:
     @parametrize
     def test_method_check(self, client: Kernel) -> None:
         proxy = client.proxies.check(
-            "id",
+            id="id",
+        )
+        assert_matches_type(ProxyCheckResponse, proxy, path=["response"])
+
+    @pytest.mark.skip(reason="Mock server tests are disabled")
+    @parametrize
+    def test_method_check_with_all_params(self, client: Kernel) -> None:
+        proxy = client.proxies.check(
+            id="id",
+            url="url",
         )
         assert_matches_type(ProxyCheckResponse, proxy, path=["response"])
 
     @pytest.mark.skip(reason="Mock server tests are disabled")
     @parametrize
     def test_raw_response_check(self, client: Kernel) -> None:
         response = client.proxies.with_raw_response.check(
-            "id",
+            id="id",
         )
 
         assert response.is_closed is True
@@ -204,7 +213,7 @@ def test_raw_response_check(self, client: Kernel) -> None:
     @parametrize
     def test_streaming_response_check(self, client: Kernel) -> None:
         with client.proxies.with_streaming_response.check(
-            "id",
+            id="id",
         ) as response:
             assert not response.is_closed
             assert response.http_request.headers.get("X-Stainless-Lang") == "python"
@@ -219,7 +228,7 @@ def test_streaming_response_check(self, client: Kernel) -> None:
     def test_path_params_check(self, client: Kernel) -> None:
         with pytest.raises(ValueError, match=r"Expected a non-empty value for `id` but received ''"):
             client.proxies.with_raw_response.check(
-                "",
+                id="",
             )
 
 
@@ -390,15 +399,24 @@ async def test_path_params_delete(self, async_client: AsyncKernel) -> None:
     @parametrize
     async def test_method_check(self, async_client: AsyncKernel) -> None:
         proxy = await async_client.proxies.check(
-            "id",
+            id="id",
+        )
+        assert_matches_type(ProxyCheckResponse, proxy, path=["response"])
+
+    @pytest.mark.skip(reason="Mock server tests are disabled")
+    @parametrize
+    async def test_method_check_with_all_params(self, async_client: AsyncKernel) -> None:
+        proxy = await async_client.proxies.check(
+            id="id",
+            url="url",
         )
         assert_matches_type(ProxyCheckResponse, proxy, path=["response"])
 
     @pytest.mark.skip(reason="Mock server tests are disabled")
     @parametrize
     async def test_raw_response_check(self, async_client: AsyncKernel) -> None:
         response = await async_client.proxies.with_raw_response.check(
-            "id",
+            id="id",
         )
 
         assert response.is_closed is True
@@ -410,7 +428,7 @@ async def test_raw_response_check(self, async_client: AsyncKernel) -> None:
     @parametrize
     async def test_streaming_response_check(self, async_client: AsyncKernel) -> None:
         async with async_client.proxies.with_streaming_response.check(
-            "id",
+            id="id",
         ) as response:
             assert not response.is_closed
             assert response.http_request.headers.get("X-Stainless-Lang") == "python"
@@ -425,5 +443,5 @@ async def test_streaming_response_check(self, async_client: AsyncKernel) -> None
     async def test_path_params_check(self, async_client: AsyncKernel) -> None:
         with pytest.raises(ValueError, match=r"Expected a non-empty value for `id` but received ''"):
             await async_client.proxies.with_raw_response.check(
-                "",
+                id="",
             )