[codex] add paginated controlplane list responses

README.md

@@ -31,6 +31,49 @@ When running Blaxel SDK from a remote server that is not Blaxel-hosted, we recom
 
 ## Usage
 
+### Paginated list responses
+
+Control plane list methods return one page at a time. The return value behaves like a list for the current page and also exposes pagination helpers:
+
+```python
+from blaxel.core import SandboxInstance
+
+page = await SandboxInstance.list(limit=50)
+
+for sandbox in page.data:
+    print(sandbox.metadata.name)
+
+if page.has_more:
+    next_page = await page.next_page()
+    print(next_page.next_cursor)
+```
+
+Use `auto_paging_iter()` only when you explicitly want the SDK to walk every page for you:
+
+```python
+page = await SandboxInstance.list(limit=50)
+
+async for sandbox in page.auto_paging_iter():
+    print(sandbox.metadata.name)
+```
+
+The same shape is used by `DriveInstance.list()`, `VolumeInstance.list()`, and job execution listing. Sync APIs expose the same fields, with a synchronous `next_page()`:
+
+```python
+from blaxel.core import SyncDriveInstance
+
+page = SyncDriveInstance.list(limit=50)
+
+while True:
+    for drive in page.data:
+        print(drive.name)
+
+    if not page.has_more:
+        break
+
+    page = page.next_page()
+```
+
 ### Sandboxes
 
 Sandboxes are secure, instant-launching compute environments that scale to zero after inactivity and resume in under 25ms.
@@ -250,8 +293,10 @@ async def main():
         ]
     })
 
-    # List volumes
-    volumes = await VolumeInstance.list()
+    # List the first page of volumes
+    volumes = await VolumeInstance.list(limit=50)
+    for listed_volume in volumes.data:
+        print(listed_volume.name)
 
     # Delete volume (using class)
     await VolumeInstance.delete("my-volume")
@@ -303,8 +348,10 @@ async def main():
     except Exception as error:
         print(f"Timeout: {error}")
 
-    # List all executions
-    executions = await job.alist_executions()
+    # List one page of executions
+    executions = await job.alist_executions(limit=20)
+    for execution in executions.data:
+        print(execution.metadata.id)
 
     # Delete an execution
     await job.acancel_execution(execution_id)

src/blaxel/core/client/api/agents/list_agents.py

@@ -5,30 +5,47 @@
 
 from ... import errors
 from ...client import Client
-from ...models.agent import Agent
+from ...models.agent_list import AgentList
 from ...models.error import Error
-from ...types import Response
+from ...models.list_agents_sort import ListAgentsSort
+from ...types import UNSET, Response, Unset
 
 
-def _get_kwargs() -> dict[str, Any]:
+def _get_kwargs(
+    *,
+    cursor: Union[Unset, str] = UNSET,
+    limit: Union[Unset, int] = 50,
+    sort: Union[Unset, ListAgentsSort] = UNSET,
+    q: Union[Unset, str] = UNSET,
+) -> dict[str, Any]:
+    params: dict[str, Any] = {}
+
+    params["cursor"] = cursor
+
+    params["limit"] = limit
+
+    json_sort: Union[Unset, str] = UNSET
+    if not isinstance(sort, Unset):
+        json_sort = sort.value
+
+    params["sort"] = json_sort
+
+    params["q"] = q
+
+    params = {k: v for k, v in params.items() if v is not UNSET and v is not None}
+
     _kwargs: dict[str, Any] = {
         "method": "get",
         "url": "/agents",
+        "params": params,
     }
 
     return _kwargs
 
 
-def _parse_response(
-    *, client: Client, response: httpx.Response
-) -> Union[Error, list["Agent"]] | None:
+def _parse_response(*, client: Client, response: httpx.Response) -> Union[AgentList, Error] | None:
     if response.status_code == 200:
-        response_200 = []
-        _response_200 = response.json()
-        for response_200_item_data in _response_200:
-            response_200_item = Agent.from_dict(response_200_item_data)
-
-            response_200.append(response_200_item)
+        response_200 = AgentList.from_dict(response.json())
 
         return response_200
     if response.status_code == 401:
@@ -51,7 +68,7 @@ def _parse_response(
 
 def _build_response(
     *, client: Client, response: httpx.Response
-) -> Response[Union[Error, list["Agent"]]]:
+) -> Response[Union[AgentList, Error]]:
     return Response(
         status_code=HTTPStatus(response.status_code),
         content=response.content,
@@ -63,21 +80,38 @@ def _build_response(
 def sync_detailed(
     *,
     client: Client,
-) -> Response[Union[Error, list["Agent"]]]:
+    cursor: Union[Unset, str] = UNSET,
+    limit: Union[Unset, int] = 50,
+    sort: Union[Unset, ListAgentsSort] = UNSET,
+    q: Union[Unset, str] = UNSET,
+) -> Response[Union[AgentList, Error]]:
     """List all agents
 
-     Returns all AI agents deployed in the workspace. Each agent includes its deployment status, runtime
-    configuration, and global inference endpoint URL.
+     Returns AI agents deployed in the workspace. Each agent includes its deployment status, runtime
+    configuration, and global inference endpoint URL. Starting with API version 2026-04-28 the response
+    is wrapped in `{data, meta}` and supports cursor pagination via the `cursor` and `limit` query
+    parameters; older versions keep returning a bare array with all agents.
+
+    Args:
+        cursor (Union[Unset, str]):
+        limit (Union[Unset, int]):  Default: 50.
+        sort (Union[Unset, ListAgentsSort]):
+        q (Union[Unset, str]):
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
         httpx.TimeoutException: If the request takes longer than Client.timeout.
 
     Returns:
-        Response[Union[Error, list['Agent']]]
+        Response[Union[AgentList, Error]]
     """
 
-    kwargs = _get_kwargs()
+    kwargs = _get_kwargs(
+        cursor=cursor,
+        limit=limit,
+        sort=sort,
+        q=q,
+    )
 
     response = client.get_httpx_client().request(
         **kwargs,
@@ -89,43 +123,76 @@ def sync_detailed(
 def sync(
     *,
     client: Client,
-) -> Union[Error, list["Agent"]] | None:
+    cursor: Union[Unset, str] = UNSET,
+    limit: Union[Unset, int] = 50,
+    sort: Union[Unset, ListAgentsSort] = UNSET,
+    q: Union[Unset, str] = UNSET,
+) -> Union[AgentList, Error] | None:
     """List all agents
 
-     Returns all AI agents deployed in the workspace. Each agent includes its deployment status, runtime
-    configuration, and global inference endpoint URL.
+     Returns AI agents deployed in the workspace. Each agent includes its deployment status, runtime
+    configuration, and global inference endpoint URL. Starting with API version 2026-04-28 the response
+    is wrapped in `{data, meta}` and supports cursor pagination via the `cursor` and `limit` query
+    parameters; older versions keep returning a bare array with all agents.
+
+    Args:
+        cursor (Union[Unset, str]):
+        limit (Union[Unset, int]):  Default: 50.
+        sort (Union[Unset, ListAgentsSort]):
+        q (Union[Unset, str]):
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
         httpx.TimeoutException: If the request takes longer than Client.timeout.
 
     Returns:
-        Union[Error, list['Agent']]
+        Union[AgentList, Error]
     """
 
     return sync_detailed(
         client=client,
+        cursor=cursor,
+        limit=limit,
+        sort=sort,
+        q=q,
     ).parsed
 
 
 async def asyncio_detailed(
     *,
     client: Client,
-) -> Response[Union[Error, list["Agent"]]]:
+    cursor: Union[Unset, str] = UNSET,
+    limit: Union[Unset, int] = 50,
+    sort: Union[Unset, ListAgentsSort] = UNSET,
+    q: Union[Unset, str] = UNSET,
+) -> Response[Union[AgentList, Error]]:
     """List all agents
 
-     Returns all AI agents deployed in the workspace. Each agent includes its deployment status, runtime
-    configuration, and global inference endpoint URL.
+     Returns AI agents deployed in the workspace. Each agent includes its deployment status, runtime
+    configuration, and global inference endpoint URL. Starting with API version 2026-04-28 the response
+    is wrapped in `{data, meta}` and supports cursor pagination via the `cursor` and `limit` query
+    parameters; older versions keep returning a bare array with all agents.
+
+    Args:
+        cursor (Union[Unset, str]):
+        limit (Union[Unset, int]):  Default: 50.
+        sort (Union[Unset, ListAgentsSort]):
+        q (Union[Unset, str]):
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
         httpx.TimeoutException: If the request takes longer than Client.timeout.
 
     Returns:
-        Response[Union[Error, list['Agent']]]
+        Response[Union[AgentList, Error]]
     """
 
-    kwargs = _get_kwargs()
+    kwargs = _get_kwargs(
+        cursor=cursor,
+        limit=limit,
+        sort=sort,
+        q=q,
+    )
 
     response = await client.get_async_httpx_client().request(**kwargs)
 
@@ -135,22 +202,38 @@ async def asyncio_detailed(
 async def asyncio(
     *,
     client: Client,
-) -> Union[Error, list["Agent"]] | None:
+    cursor: Union[Unset, str] = UNSET,
+    limit: Union[Unset, int] = 50,
+    sort: Union[Unset, ListAgentsSort] = UNSET,
+    q: Union[Unset, str] = UNSET,
+) -> Union[AgentList, Error] | None:
     """List all agents
 
-     Returns all AI agents deployed in the workspace. Each agent includes its deployment status, runtime
-    configuration, and global inference endpoint URL.
+     Returns AI agents deployed in the workspace. Each agent includes its deployment status, runtime
+    configuration, and global inference endpoint URL. Starting with API version 2026-04-28 the response
+    is wrapped in `{data, meta}` and supports cursor pagination via the `cursor` and `limit` query
+    parameters; older versions keep returning a bare array with all agents.
+
+    Args:
+        cursor (Union[Unset, str]):
+        limit (Union[Unset, int]):  Default: 50.
+        sort (Union[Unset, ListAgentsSort]):
+        q (Union[Unset, str]):
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
         httpx.TimeoutException: If the request takes longer than Client.timeout.
 
     Returns:
-        Union[Error, list['Agent']]
+        Union[AgentList, Error]
     """
 
     return (
         await asyncio_detailed(
             client=client,
+            cursor=cursor,
+            limit=limit,
+            sort=sort,
+            q=q,
         )
     ).parsed