feat: Align Task Filtering by Status with status Field

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 26
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browser-use%2Fbrowser-use-890b9140b139df6307d175ff31cba0bf14d703887bee2f0a8db9f5bffc78e11d.yml
-openapi_spec_hash: 7131a3daffe4f5b67bc1c7ccec06d961
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/browser-use%2Fbrowser-use-3a9488448292a0736b08b2d6427e702eaf7106d86345ca2e65b64bed4398b036.yml
+openapi_spec_hash: 5ff2781dcc11a0c9aa353f5cb14bcc16
 config_hash: 9d52be5177b2ede4cb0633c04f4cc4ef

src/browser_use_sdk/resources/tasks.py

@@ -2,12 +2,13 @@
 
 from __future__ import annotations
 
-from typing import Dict, List, Optional
+from typing import Dict, List, Union, Optional
+from datetime import datetime
 from typing_extensions import Literal
 
 import httpx
 
-from ..types import task_list_params, task_create_params, task_update_params
+from ..types import TaskStatus, task_list_params, task_create_params, task_update_params
 from .._types import NOT_GIVEN, Body, Query, Headers, NotGiven
 from .._utils import maybe_transform, async_maybe_transform
 from .._compat import cached_property
@@ -20,6 +21,7 @@
 )
 from .._base_client import make_request_options
 from ..types.task_view import TaskView
+from ..types.task_status import TaskStatus
 from ..types.task_list_response import TaskListResponse
 from ..types.task_create_response import TaskCreateResponse
 from ..types.task_get_logs_response import TaskGetLogsResponse
@@ -280,8 +282,9 @@ def update(
     def list(
         self,
         *,
-        filter_by: Optional[Literal["started", "paused", "stopped", "finished", "successful", "unsuccessful"]]
-        | NotGiven = NOT_GIVEN,
+        after: Union[str, datetime, None] | NotGiven = NOT_GIVEN,
+        before: Union[str, datetime, None] | NotGiven = NOT_GIVEN,
+        filter_by: Optional[TaskStatus] | NotGiven = NOT_GIVEN,
         page_number: int | NotGiven = NOT_GIVEN,
         page_size: int | NotGiven = NOT_GIVEN,
         session_id: Optional[str] | NotGiven = NOT_GIVEN,
@@ -293,32 +296,26 @@ def list(
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> TaskListResponse:
         """
-        Get a paginated list of all AI agent tasks for the authenticated user.
+        Get a paginated list of all Browser Use Agent tasks for the authenticated user.
 
-        AI agent tasks are the individual jobs that your agents perform within a
-        session. Each task represents a specific instruction or goal that the agent
+        Browser Use Agent tasks are the individual jobs that your agents perform within
+        a session. Each task represents a specific instruction or goal that the agent
         works on, such as filling out a form, extracting data, or navigating to specific
         pages.
 
-        You can control what data is included for each task:
-
-        - Task steps: Detailed actions the agent took
-        - User uploaded files: Files you provided for the task
-        - Output files: Files generated by the agent during the task
-
         Returns:
 
-        - A paginated list of agent tasks
-        - Total count of tasks
+        - A paginated list of Browser Use Agent tasks
+        - Total count of Browser Use Agent tasks
         - Page information for navigation
-        - Optional detailed data based on your parameters
 
         Args:
-          filter_by: Enumeration of possible task filters
+          filter_by: Enumeration of possible task execution states
 
-              Attributes: STARTED: All started tasks PAUSED: All paused tasks STOPPED: All
-              stopped tasks FINISHED: All finished tasks SUCCESSFUL: All successful tasks
-              UNSUCCESSFUL: All unsuccessful tasks
+              Attributes: STARTED: Task has been started and is currently running. PAUSED:
+              Task execution has been temporarily paused (can be resumed) FINISHED: Task has
+              finished and the agent has completed the task. STOPPED: Task execution has been
+              manually stopped (cannot be resumed).
 
           extra_headers: Send extra headers
 
@@ -337,6 +334,8 @@ def list(
                 timeout=timeout,
                 query=maybe_transform(
                     {
+                        "after": after,
+                        "before": before,
                         "filter_by": filter_by,
                         "page_number": page_number,
                         "page_size": page_size,
@@ -778,8 +777,9 @@ async def update(
     async def list(
         self,
         *,
-        filter_by: Optional[Literal["started", "paused", "stopped", "finished", "successful", "unsuccessful"]]
-        | NotGiven = NOT_GIVEN,
+        after: Union[str, datetime, None] | NotGiven = NOT_GIVEN,
+        before: Union[str, datetime, None] | NotGiven = NOT_GIVEN,
+        filter_by: Optional[TaskStatus] | NotGiven = NOT_GIVEN,
         page_number: int | NotGiven = NOT_GIVEN,
         page_size: int | NotGiven = NOT_GIVEN,
         session_id: Optional[str] | NotGiven = NOT_GIVEN,
@@ -791,32 +791,26 @@ async def list(
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
     ) -> TaskListResponse:
         """
-        Get a paginated list of all AI agent tasks for the authenticated user.
+        Get a paginated list of all Browser Use Agent tasks for the authenticated user.
 
-        AI agent tasks are the individual jobs that your agents perform within a
-        session. Each task represents a specific instruction or goal that the agent
+        Browser Use Agent tasks are the individual jobs that your agents perform within
+        a session. Each task represents a specific instruction or goal that the agent
         works on, such as filling out a form, extracting data, or navigating to specific
         pages.
 
-        You can control what data is included for each task:
-
-        - Task steps: Detailed actions the agent took
-        - User uploaded files: Files you provided for the task
-        - Output files: Files generated by the agent during the task
-
         Returns:
 
-        - A paginated list of agent tasks
-        - Total count of tasks
+        - A paginated list of Browser Use Agent tasks
+        - Total count of Browser Use Agent tasks
         - Page information for navigation
-        - Optional detailed data based on your parameters
 
         Args:
-          filter_by: Enumeration of possible task filters
+          filter_by: Enumeration of possible task execution states
 
-              Attributes: STARTED: All started tasks PAUSED: All paused tasks STOPPED: All
-              stopped tasks FINISHED: All finished tasks SUCCESSFUL: All successful tasks
-              UNSUCCESSFUL: All unsuccessful tasks
+              Attributes: STARTED: Task has been started and is currently running. PAUSED:
+              Task execution has been temporarily paused (can be resumed) FINISHED: Task has
+              finished and the agent has completed the task. STOPPED: Task execution has been
+              manually stopped (cannot be resumed).
 
           extra_headers: Send extra headers
 
@@ -835,6 +829,8 @@ async def list(
                 timeout=timeout,
                 query=await async_maybe_transform(
                     {
+                        "after": after,
+                        "before": before,
                         "filter_by": filter_by,
                         "page_number": page_number,
                         "page_size": page_size,

src/browser_use_sdk/types/task_item_view.py

@@ -26,9 +26,10 @@ class TaskItemView(BaseModel):
     status: TaskStatus
     """Enumeration of possible task execution states
 
-    Attributes: STARTED: Task has been started and is currently running PAUSED: Task
-    execution has been temporarily paused (can be resumed) STOPPED: Task execution
-    has been stopped (cannot be resumed) FINISHED: Task has completed successfully
+    Attributes: STARTED: Task has been started and is currently running. PAUSED:
+    Task execution has been temporarily paused (can be resumed) FINISHED: Task has
+    finished and the agent has completed the task. STOPPED: Task execution has been
+    manually stopped (cannot be resumed).
     """
 
     task: str

src/browser_use_sdk/types/task_list_params.py

@@ -2,24 +2,28 @@
 
 from __future__ import annotations
 
-from typing import Optional
-from typing_extensions import Literal, Annotated, TypedDict
+from typing import Union, Optional
+from datetime import datetime
+from typing_extensions import Annotated, TypedDict
 
 from .._utils import PropertyInfo
+from .task_status import TaskStatus
 
 __all__ = ["TaskListParams"]
 
 
 class TaskListParams(TypedDict, total=False):
-    filter_by: Annotated[
-        Optional[Literal["started", "paused", "stopped", "finished", "successful", "unsuccessful"]],
-        PropertyInfo(alias="filterBy"),
-    ]
-    """Enumeration of possible task filters
-
-    Attributes: STARTED: All started tasks PAUSED: All paused tasks STOPPED: All
-    stopped tasks FINISHED: All finished tasks SUCCESSFUL: All successful tasks
-    UNSUCCESSFUL: All unsuccessful tasks
+    after: Annotated[Union[str, datetime, None], PropertyInfo(format="iso8601")]
+
+    before: Annotated[Union[str, datetime, None], PropertyInfo(format="iso8601")]
+
+    filter_by: Annotated[Optional[TaskStatus], PropertyInfo(alias="filterBy")]
+    """Enumeration of possible task execution states
+
+    Attributes: STARTED: Task has been started and is currently running. PAUSED:
+    Task execution has been temporarily paused (can be resumed) FINISHED: Task has
+    finished and the agent has completed the task. STOPPED: Task execution has been
+    manually stopped (cannot be resumed).
     """
 
     page_number: Annotated[int, PropertyInfo(alias="pageNumber")]

src/browser_use_sdk/types/task_status.py

@@ -4,4 +4,4 @@
 
 __all__ = ["TaskStatus"]
 
-TaskStatus: TypeAlias = Literal["started", "paused", "stopped", "finished"]
+TaskStatus: TypeAlias = Literal["started", "paused", "finished", "stopped"]

src/browser_use_sdk/types/task_view.py

@@ -57,9 +57,10 @@ class TaskView(BaseModel):
     status: TaskStatus
     """Enumeration of possible task execution states
 
-    Attributes: STARTED: Task has been started and is currently running PAUSED: Task
-    execution has been temporarily paused (can be resumed) STOPPED: Task execution
-    has been stopped (cannot be resumed) FINISHED: Task has completed successfully
+    Attributes: STARTED: Task has been started and is currently running. PAUSED:
+    Task execution has been temporarily paused (can be resumed) FINISHED: Task has
+    finished and the agent has completed the task. STOPPED: Task execution has been
+    manually stopped (cannot be resumed).
     """
 
     steps: List[TaskStepView]

tests/api_resources/test_tasks.py

@@ -17,6 +17,7 @@
     TaskGetOutputFileResponse,
     TaskGetUserUploadedFileResponse,
 )
+from browser_use_sdk._utils import parse_datetime
 
 base_url = os.environ.get("TEST_API_BASE_URL", "http://127.0.0.1:4010")
 
@@ -177,6 +178,8 @@ def test_method_list(self, client: BrowserUse) -> None:
     @parametrize
     def test_method_list_with_all_params(self, client: BrowserUse) -> None:
         task = client.tasks.list(
+            after=parse_datetime("2019-12-27T18:11:19.117Z"),
+            before=parse_datetime("2019-12-27T18:11:19.117Z"),
             filter_by="started",
             page_number=1,
             page_size=1,
@@ -511,6 +514,8 @@ async def test_method_list(self, async_client: AsyncBrowserUse) -> None:
     @parametrize
     async def test_method_list_with_all_params(self, async_client: AsyncBrowserUse) -> None:
         task = await async_client.tasks.list(
+            after=parse_datetime("2019-12-27T18:11:19.117Z"),
+            before=parse_datetime("2019-12-27T18:11:19.117Z"),
             filter_by="started",
             page_number=1,
             page_size=1,