feat(api): add since parameter to deployment logs endpoint

stainless-app[bot] · stainless-app[bot] · commit 5a94cbd013cc · 2025-06-24T19:53:00.000Z
diff --git a/.stats.yml b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 16
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-b019e469425a59061f37c5fdc7a131a5291c66134ef0627db4f06bb1f4af0b15.yml
-openapi_spec_hash: f66a3c2efddb168db9539ba2507b10b8
-config_hash: aae6721b2be9ec8565dfc8f7eadfe105
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-2aec229ccf91f7c1ac95aa675ea2a59bd61af9e363a22c3b49677992f1eeb16a.yml
+openapi_spec_hash: c80cd5d52a79cd5366a76d4a825bd27a
+config_hash: b8e1fff080fbaa22656ab0a57b591777
diff --git a/api.md b/api.md
@@ -1,7 +1,7 @@
 # Shared Types
 
 ```python
-from kernel.types import ErrorDetail, ErrorEvent, ErrorModel, LogEvent
+from kernel.types import ErrorDetail, ErrorEvent, ErrorModel, HeartbeatEvent, LogEvent
 ```
 
 # Deployments
@@ -21,7 +21,7 @@ Methods:
 
 - <code title="post /deployments">client.deployments.<a href="./src/kernel/resources/deployments.py">create</a>(\*\*<a href="src/kernel/types/deployment_create_params.py">params</a>) -> <a href="./src/kernel/types/deployment_create_response.py">DeploymentCreateResponse</a></code>
 - <code title="get /deployments/{id}">client.deployments.<a href="./src/kernel/resources/deployments.py">retrieve</a>(id) -> <a href="./src/kernel/types/deployment_retrieve_response.py">DeploymentRetrieveResponse</a></code>
-- <code title="get /deployments/{id}/events">client.deployments.<a href="./src/kernel/resources/deployments.py">follow</a>(id) -> <a href="./src/kernel/types/deployment_follow_response.py">DeploymentFollowResponse</a></code>
+- <code title="get /deployments/{id}/events">client.deployments.<a href="./src/kernel/resources/deployments.py">follow</a>(id, \*\*<a href="src/kernel/types/deployment_follow_params.py">params</a>) -> <a href="./src/kernel/types/deployment_follow_response.py">DeploymentFollowResponse</a></code>
 
 # Apps
 
diff --git a/src/kernel/resources/deployments.py b/src/kernel/resources/deployments.py
@@ -7,7 +7,7 @@
 
 import httpx
 
-from ..types import deployment_create_params
+from ..types import deployment_create_params, deployment_follow_params
 from .._types import NOT_GIVEN, Body, Query, Headers, NotGiven, FileTypes
 from .._utils import extract_files, maybe_transform, deepcopy_minimal, async_maybe_transform
 from .._compat import cached_property
@@ -150,6 +150,7 @@ def follow(
         self,
         id: str,
         *,
+        since: str | NotGiven = NOT_GIVEN,
         # 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,
@@ -163,6 +164,8 @@ def follow(
         deployment reaches a terminal state.
 
         Args:
+          since: Show logs since the given time (RFC timestamps or durations like 5m).
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -177,7 +180,11 @@ def follow(
         return self._get(
             f"/deployments/{id}/events",
             options=make_request_options(
-                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                query=maybe_transform({"since": since}, deployment_follow_params.DeploymentFollowParams),
             ),
             cast_to=cast(
                 Any, DeploymentFollowResponse
@@ -310,6 +317,7 @@ async def follow(
         self,
         id: str,
         *,
+        since: str | NotGiven = NOT_GIVEN,
         # 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,
@@ -323,6 +331,8 @@ async def follow(
         deployment reaches a terminal state.
 
         Args:
+          since: Show logs since the given time (RFC timestamps or durations like 5m).
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -337,7 +347,11 @@ async def follow(
         return await self._get(
             f"/deployments/{id}/events",
             options=make_request_options(
-                extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                query=await async_maybe_transform({"since": since}, deployment_follow_params.DeploymentFollowParams),
             ),
             cast_to=cast(
                 Any, DeploymentFollowResponse
diff --git a/src/kernel/types/__init__.py b/src/kernel/types/__init__.py
@@ -2,7 +2,13 @@
 
 from __future__ import annotations
 
-from .shared import LogEvent as LogEvent, ErrorEvent as ErrorEvent, ErrorModel as ErrorModel, ErrorDetail as ErrorDetail
+from .shared import (
+    LogEvent as LogEvent,
+    ErrorEvent as ErrorEvent,
+    ErrorModel as ErrorModel,
+    ErrorDetail as ErrorDetail,
+    HeartbeatEvent as HeartbeatEvent,
+)
 from .app_list_params import AppListParams as AppListParams
 from .app_list_response import AppListResponse as AppListResponse
 from .browser_persistence import BrowserPersistence as BrowserPersistence
@@ -13,6 +19,7 @@
 from .invocation_state_event import InvocationStateEvent as InvocationStateEvent
 from .browser_create_response import BrowserCreateResponse as BrowserCreateResponse
 from .deployment_create_params import DeploymentCreateParams as DeploymentCreateParams
+from .deployment_follow_params import DeploymentFollowParams as DeploymentFollowParams
 from .invocation_create_params import InvocationCreateParams as InvocationCreateParams
 from .invocation_update_params import InvocationUpdateParams as InvocationUpdateParams
 from .browser_persistence_param import BrowserPersistenceParam as BrowserPersistenceParam
diff --git a/src/kernel/types/app_list_response.py b/src/kernel/types/app_list_response.py
@@ -15,6 +15,9 @@ class AppListResponseItem(BaseModel):
     app_name: str
     """Name of the application"""
 
+    deployment: str
+    """Deployment ID"""
+
     region: Literal["aws.us-east-1a"]
     """Deployment region code"""
 
diff --git a/src/kernel/types/apps/deployment_follow_response.py b/src/kernel/types/apps/deployment_follow_response.py
@@ -7,6 +7,7 @@
 from ..._utils import PropertyInfo
 from ..._models import BaseModel
 from ..shared.log_event import LogEvent
+from ..shared.heartbeat_event import HeartbeatEvent
 
 __all__ = ["DeploymentFollowResponse", "StateEvent", "StateUpdateEvent"]
 
@@ -36,5 +37,5 @@ class StateUpdateEvent(BaseModel):
 
 
 DeploymentFollowResponse: TypeAlias = Annotated[
-    Union[StateEvent, StateUpdateEvent, LogEvent], PropertyInfo(discriminator="event")
+    Union[StateEvent, StateUpdateEvent, LogEvent, HeartbeatEvent], PropertyInfo(discriminator="event")
 ]
diff --git a/src/kernel/types/deployment_follow_params.py b/src/kernel/types/deployment_follow_params.py
@@ -0,0 +1,12 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import TypedDict
+
+__all__ = ["DeploymentFollowParams"]
+
+
+class DeploymentFollowParams(TypedDict, total=False):
+    since: str
+    """Show logs since the given time (RFC timestamps or durations like 5m)."""
diff --git a/src/kernel/types/deployment_follow_response.py b/src/kernel/types/deployment_follow_response.py
@@ -9,6 +9,7 @@
 from .shared.log_event import LogEvent
 from .shared.error_event import ErrorEvent
 from .deployment_state_event import DeploymentStateEvent
+from .shared.heartbeat_event import HeartbeatEvent
 
 __all__ = ["DeploymentFollowResponse", "AppVersionSummaryEvent", "AppVersionSummaryEventAction"]
 
@@ -45,5 +46,6 @@ class AppVersionSummaryEvent(BaseModel):
 
 
 DeploymentFollowResponse: TypeAlias = Annotated[
-    Union[LogEvent, DeploymentStateEvent, AppVersionSummaryEvent, ErrorEvent], PropertyInfo(discriminator="event")
+    Union[LogEvent, DeploymentStateEvent, AppVersionSummaryEvent, ErrorEvent, HeartbeatEvent],
+    PropertyInfo(discriminator="event"),
 ]
diff --git a/src/kernel/types/invocation_follow_response.py b/src/kernel/types/invocation_follow_response.py
@@ -7,9 +7,10 @@
 from .shared.log_event import LogEvent
 from .shared.error_event import ErrorEvent
 from .invocation_state_event import InvocationStateEvent
+from .shared.heartbeat_event import HeartbeatEvent
 
 __all__ = ["InvocationFollowResponse"]
 
 InvocationFollowResponse: TypeAlias = Annotated[
-    Union[LogEvent, InvocationStateEvent, ErrorEvent], PropertyInfo(discriminator="event")
+    Union[LogEvent, InvocationStateEvent, ErrorEvent, HeartbeatEvent], PropertyInfo(discriminator="event")
 ]
diff --git a/src/kernel/types/shared/__init__.py b/src/kernel/types/shared/__init__.py
@@ -4,3 +4,4 @@
 from .error_event import ErrorEvent as ErrorEvent
 from .error_model import ErrorModel as ErrorModel
 from .error_detail import ErrorDetail as ErrorDetail
+from .heartbeat_event import HeartbeatEvent as HeartbeatEvent
diff --git a/src/kernel/types/shared/heartbeat_event.py b/src/kernel/types/shared/heartbeat_event.py
@@ -0,0 +1,16 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from datetime import datetime
+from typing_extensions import Literal
+
+from ..._models import BaseModel
+
+__all__ = ["HeartbeatEvent"]
+
+
+class HeartbeatEvent(BaseModel):
+    event: Literal["sse_heartbeat"]
+    """Event type identifier (always "sse_heartbeat")."""
+
+    timestamp: datetime
+    """Time the heartbeat was sent."""
diff --git a/tests/api_resources/test_deployments.py b/tests/api_resources/test_deployments.py
@@ -9,7 +9,10 @@
 
 from kernel import Kernel, AsyncKernel
 from tests.utils import assert_matches_type
-from kernel.types import DeploymentCreateResponse, DeploymentRetrieveResponse
+from kernel.types import (
+    DeploymentCreateResponse,
+    DeploymentRetrieveResponse,
+)
 
 base_url = os.environ.get("TEST_API_BASE_URL", "http://127.0.0.1:4010")
 
@@ -115,7 +118,18 @@ def test_path_params_retrieve(self, client: Kernel) -> None:
     @parametrize
     def test_method_follow(self, client: Kernel) -> None:
         deployment_stream = client.deployments.follow(
-            "id",
+            id="id",
+        )
+        deployment_stream.response.close()
+
+    @pytest.mark.skip(
+        reason="currently no good way to test endpoints with content type text/event-stream, Prism mock server will fail"
+    )
+    @parametrize
+    def test_method_follow_with_all_params(self, client: Kernel) -> None:
+        deployment_stream = client.deployments.follow(
+            id="id",
+            since="2025-06-20T12:00:00Z",
         )
         deployment_stream.response.close()
 
@@ -125,7 +139,7 @@ def test_method_follow(self, client: Kernel) -> None:
     @parametrize
     def test_raw_response_follow(self, client: Kernel) -> None:
         response = client.deployments.with_raw_response.follow(
-            "id",
+            id="id",
         )
 
         assert response.http_request.headers.get("X-Stainless-Lang") == "python"
@@ -138,7 +152,7 @@ def test_raw_response_follow(self, client: Kernel) -> None:
     @parametrize
     def test_streaming_response_follow(self, client: Kernel) -> None:
         with client.deployments.with_streaming_response.follow(
-            "id",
+            id="id",
         ) as response:
             assert not response.is_closed
             assert response.http_request.headers.get("X-Stainless-Lang") == "python"
@@ -155,7 +169,7 @@ def test_streaming_response_follow(self, client: Kernel) -> None:
     def test_path_params_follow(self, client: Kernel) -> None:
         with pytest.raises(ValueError, match=r"Expected a non-empty value for `id` but received ''"):
             client.deployments.with_raw_response.follow(
-                "",
+                id="",
             )
 
 
@@ -262,7 +276,18 @@ async def test_path_params_retrieve(self, async_client: AsyncKernel) -> None:
     @parametrize
     async def test_method_follow(self, async_client: AsyncKernel) -> None:
         deployment_stream = await async_client.deployments.follow(
-            "id",
+            id="id",
+        )
+        await deployment_stream.response.aclose()
+
+    @pytest.mark.skip(
+        reason="currently no good way to test endpoints with content type text/event-stream, Prism mock server will fail"
+    )
+    @parametrize
+    async def test_method_follow_with_all_params(self, async_client: AsyncKernel) -> None:
+        deployment_stream = await async_client.deployments.follow(
+            id="id",
+            since="2025-06-20T12:00:00Z",
         )
         await deployment_stream.response.aclose()
 
@@ -272,7 +297,7 @@ async def test_method_follow(self, async_client: AsyncKernel) -> None:
     @parametrize
     async def test_raw_response_follow(self, async_client: AsyncKernel) -> None:
         response = await async_client.deployments.with_raw_response.follow(
-            "id",
+            id="id",
         )
 
         assert response.http_request.headers.get("X-Stainless-Lang") == "python"
@@ -285,7 +310,7 @@ async def test_raw_response_follow(self, async_client: AsyncKernel) -> None:
     @parametrize
     async def test_streaming_response_follow(self, async_client: AsyncKernel) -> None:
         async with async_client.deployments.with_streaming_response.follow(
-            "id",
+            id="id",
         ) as response:
             assert not response.is_closed
             assert response.http_request.headers.get("X-Stainless-Lang") == "python"
@@ -302,5 +327,5 @@ async def test_streaming_response_follow(self, async_client: AsyncKernel) -> Non
     async def test_path_params_follow(self, async_client: AsyncKernel) -> None:
         with pytest.raises(ValueError, match=r"Expected a non-empty value for `id` but received ''"):
             await async_client.deployments.with_raw_response.follow(
-                "",
+                id="",
             )
