From 4209ed4d63ca9bfc6a850e6fbed60e4e12b941cc Mon Sep 17 00:00:00 2001
From: cthomas <caren@letta.com>
Date: Mon, 15 Sep 2025 21:55:01 -0700
Subject: [PATCH] feat: add pagination to list groups messages endpoint (#2945)

---
 letta/server/rest_api/routers/v1/groups.py | 21 ++++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/letta/server/rest_api/routers/v1/groups.py b/letta/server/rest_api/routers/v1/groups.py
index b6d33592..6c8063b1 100644
--- a/letta/server/rest_api/routers/v1/groups.py
+++ b/letta/server/rest_api/routers/v1/groups.py
@@ -233,13 +233,23 @@ async def modify_group_message(
 @router.get("/{group_id}/messages", response_model=GroupMessagesResponse, operation_id="list_group_messages")
 async def list_group_messages(
     group_id: str,
-    server: "SyncServer" = Depends(get_letta_server),
-    after: Optional[str] = Query(None, description="Message after which to retrieve the returned messages."),
-    before: Optional[str] = Query(None, description="Message before which to retrieve the returned messages."),
-    limit: int = Query(10, description="Maximum number of messages to retrieve."),
+    before: Optional[str] = Query(
+        None,
+        description="Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order",
+    ),
+    after: Optional[str] = Query(
+        None,
+        description="Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order",
+    ),
+    limit: Optional[int] = Query(10, description="Maximum number of messages to retrieve"),
+    order: Literal["asc", "desc"] = Query(
+        "desc", description="Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first"
+    ),
+    order_by: Literal["created_at"] = Query("created_at", description="Field to sort by"),
     use_assistant_message: bool = Query(True, description="Whether to use assistant messages"),
     assistant_message_tool_name: str = Query(DEFAULT_MESSAGE_TOOL, description="The name of the designated message tool."),
     assistant_message_tool_kwarg: str = Query(DEFAULT_MESSAGE_TOOL_KWARG, description="The name of the message argument."),
+    server: "SyncServer" = Depends(get_letta_server),
     headers: HeaderParams = Depends(get_headers),
 ):
     """
@@ -255,7 +265,7 @@ async def list_group_messages(
             before=before,
             limit=limit,
             group_id=group_id,
-            reverse=True,
+            reverse=(order == "desc"),
             return_message_object=False,
             use_assistant_message=use_assistant_message,
             assistant_message_tool_name=assistant_message_tool_name,
@@ -267,6 +277,7 @@ async def list_group_messages(
             after=after,
             before=before,
             limit=limit,
+            ascending=(order == "asc"),
             actor=actor,
             use_assistant_message=use_assistant_message,
             assistant_message_tool_name=assistant_message_tool_name,