letta-nightly 0.12.1.dev20251024104217__py3-none-any.whl → 0.13.0.dev20251025104015__py3-none-any.whl

letta/server/rest_api/routers/v1/folders.py

@@ -1,7 +1,7 @@
 import mimetypes
 import os
 import tempfile
-from pathlib import Path
+from pathlib import Path as PathLibPath
 from typing import List, Literal, Optional
 
 from fastapi import APIRouter, Depends, HTTPException, Query, UploadFile
@@ -9,6 +9,7 @@ from starlette import status
 from starlette.responses import Response
 
 import letta.constants as constants
+from letta.errors import LettaInvalidArgumentError, LettaUnsupportedFileUploadError
 from letta.helpers.pinecone_utils import (
     delete_file_records_from_pinecone_index,
     delete_source_records_from_pinecone_index,
@@ -20,10 +21,10 @@ from letta.otel.tracing import trace_method
 from letta.schemas.agent import AgentState
 from letta.schemas.embedding_config import EmbeddingConfig
 from letta.schemas.enums import DuplicateFileHandling, FileProcessingStatus
-from letta.schemas.file import FileMetadata
-from letta.schemas.folder import Folder
+from letta.schemas.file import FileMetadata, FileMetadataBase
+from letta.schemas.folder import BaseFolder, Folder
 from letta.schemas.passage import Passage
-from letta.schemas.source import Source, SourceCreate, SourceUpdate
+from letta.schemas.source import BaseSource, Source, SourceCreate, SourceUpdate
 from letta.schemas.source_metadata import OrganizationSourcesStats
 from letta.schemas.user import User
 from letta.server.rest_api.dependencies import HeaderParams, get_headers, get_letta_server
@@ -36,6 +37,7 @@ from letta.services.file_processor.parser.markitdown_parser import MarkitdownFil
 from letta.services.file_processor.parser.mistral_parser import MistralFileParser
 from letta.settings import settings
 from letta.utils import safe_create_file_processing_task, safe_create_task, sanitize_filename
+from letta.validators import FileId, FolderId
 
 logger = get_logger(__name__)
 
@@ -60,7 +62,7 @@ async def count_folders(
 
 @router.get("/{folder_id}", response_model=Folder, operation_id="retrieve_folder")
 async def retrieve_folder(
-    folder_id: str,
+    folder_id: FolderId,
     server: "SyncServer" = Depends(get_letta_server),
     headers: HeaderParams = Depends(get_headers),
 ):
@@ -70,8 +72,6 @@ async def retrieve_folder(
     actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
 
     folder = await server.source_manager.get_source_by_id(source_id=folder_id, actor=actor)
-    if not folder:
-        raise HTTPException(status_code=404, detail=f"Folder with id={folder_id} not found.")
     return folder
 
 
@@ -90,8 +90,6 @@ async def get_folder_by_name(
     actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
 
     folder = await server.source_manager.get_source_by_name(source_name=folder_name, actor=actor)
-    if not folder:
-        raise HTTPException(status_code=404, detail=f"Folder with name={folder_name} not found.")
     return folder.id
 
 
@@ -157,8 +155,9 @@ async def create_folder(
     if not folder_create.embedding_config:
         if not folder_create.embedding:
             if settings.default_embedding_handle is None:
-                # TODO: modify error type
-                raise ValueError("Must specify either embedding or embedding_config in request")
+                raise LettaInvalidArgumentError(
+                    "Must specify either embedding or embedding_config in request", argument_name="default_embedding_handle"
+                )
             else:
                 folder_create.embedding = settings.default_embedding_handle
         folder_create.embedding_config = await server.get_embedding_config_from_handle_async(
@@ -178,8 +177,8 @@ async def create_folder(
 
 @router.patch("/{folder_id}", response_model=Folder, operation_id="modify_folder")
 async def modify_folder(
-    folder_id: str,
     folder: SourceUpdate,
+    folder_id: FolderId,
     server: "SyncServer" = Depends(get_letta_server),
     headers: HeaderParams = Depends(get_headers),
 ):
@@ -188,14 +187,13 @@ async def modify_folder(
     """
     # TODO: allow updating the handle/embedding config
     actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
-    if not await server.source_manager.get_source_by_id(source_id=folder_id, actor=actor):
-        raise HTTPException(status_code=404, detail=f"Folder with id={folder_id} does not exist.")
+    await server.source_manager.get_source_by_id(source_id=folder_id, actor=actor)
     return await server.source_manager.update_source(source_id=folder_id, source_update=folder, actor=actor)
 
 
 @router.delete("/{folder_id}", response_model=None, operation_id="delete_folder")
 async def delete_folder(
-    folder_id: str,
+    folder_id: FolderId,
     server: "SyncServer" = Depends(get_letta_server),
     headers: HeaderParams = Depends(get_headers),
 ):
@@ -222,18 +220,16 @@ async def delete_folder(
         await server.remove_files_from_context_window(agent_state=agent_state, file_ids=file_ids, actor=actor)
 
         if agent_state.enable_sleeptime:
-            try:
-                block = await server.agent_manager.get_block_with_label_async(agent_id=agent_state.id, block_label=folder.name, actor=actor)
+            block = await server.agent_manager.get_block_with_label_async(agent_id=agent_state.id, block_label=folder.name, actor=actor)
+            if block:
                 await server.block_manager.delete_block_async(block.id, actor)
-            except:
-                pass
     await server.delete_source(source_id=folder_id, actor=actor)
 
 
 @router.post("/{folder_id}/upload", response_model=FileMetadata, operation_id="upload_file_to_folder")
 async def upload_file_to_folder(
     file: UploadFile,
-    folder_id: str,
+    folder_id: FolderId,
     duplicate_handling: DuplicateFileHandling = Query(DuplicateFileHandling.SUFFIX, description="How to handle duplicate filenames"),
     name: Optional[str] = Query(None, description="Optional custom name to override the uploaded file's name"),
     server: "SyncServer" = Depends(get_letta_server),
@@ -259,15 +255,14 @@ async def upload_file_to_folder(
         media_type = (guessed or "").lower()
 
         if media_type not in allowed_media_types:
-            ext = Path(file.filename).suffix.lower()
+            ext = PathLibPath(file.filename).suffix.lower()
             ext_map = get_extension_to_mime_type_map()
             media_type = ext_map.get(ext, media_type)
 
     # If still not allowed, reject with 415.
     if media_type not in allowed_media_types:
-        raise HTTPException(
-            status_code=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE,
-            detail=(
+        raise LettaUnsupportedFileUploadError(
+            message=(
                 f"Unsupported file type: {media_type or 'unknown'} "
                 f"(filename: {file.filename}). "
                 f"Supported types: PDF, text files (.txt, .md), JSON, and code files (.py, .js, .java, etc.)."
@@ -277,8 +272,6 @@ async def upload_file_to_folder(
     actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
 
     folder = await server.source_manager.get_source_by_id(source_id=folder_id, actor=actor)
-    if folder is None:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Folder with id={folder_id} not found.")
 
     content = await file.read()
 
@@ -297,8 +290,9 @@ async def upload_file_to_folder(
     if existing_file:
         # Duplicate found, handle based on strategy
         if duplicate_handling == DuplicateFileHandling.ERROR:
-            raise HTTPException(
-                status_code=status.HTTP_409_CONFLICT, detail=f"File '{original_filename}' already exists in folder '{folder.name}'"
+            raise LettaInvalidArgumentError(
+                message=f"File '{original_filename}' already exists in folder '{folder.name}'",
+                argument_name="duplicate_handling",
             )
         elif duplicate_handling == DuplicateFileHandling.SKIP:
             # Return existing file metadata with custom header to indicate it was skipped
@@ -350,7 +344,7 @@ async def upload_file_to_folder(
 
 @router.get("/{folder_id}/agents", response_model=List[str], operation_id="list_agents_for_folder")
 async def list_agents_for_folder(
-    folder_id: str,
+    folder_id: FolderId,
     before: Optional[str] = Query(
         None,
         description="Agent ID cursor for pagination. Returns agents that come before this agent ID in the specified sort order",
@@ -383,7 +377,7 @@ async def list_agents_for_folder(
 
 @router.get("/{folder_id}/passages", response_model=List[Passage], operation_id="list_folder_passages")
 async def list_folder_passages(
-    folder_id: str,
+    folder_id: FolderId,
     before: Optional[str] = Query(
         None,
         description="Passage ID cursor for pagination. Returns passages that come before this passage ID in the specified sort order",
@@ -416,7 +410,7 @@ async def list_folder_passages(
 
 @router.get("/{folder_id}/files", response_model=List[FileMetadata], operation_id="list_folder_files")
 async def list_folder_files(
-    folder_id: str,
+    folder_id: FolderId,
     before: Optional[str] = Query(
         None,
         description="File ID cursor for pagination. Returns files that come before this file ID in the specified sort order",
@@ -503,8 +497,8 @@ async def list_folder_files(
 # it's still good practice to return a status indicating the success or failure of the deletion
 @router.delete("/{folder_id}/{file_id}", status_code=204, operation_id="delete_file_from_folder")
 async def delete_file_from_folder(
-    folder_id: str,
-    file_id: str,
+    folder_id: FolderId,
+    file_id: FileId,
     server: "SyncServer" = Depends(get_letta_server),
     headers: HeaderParams = Depends(get_headers),
 ):
@@ -528,8 +522,6 @@ async def delete_file_from_folder(
         await delete_file_records_from_pinecone_index(file_id=file_id, actor=actor)
 
     safe_create_task(sleeptime_document_ingest_async(server, folder_id, actor, clear_history=True), label="document_ingest_after_delete")
-    if deleted_file is None:
-        raise HTTPException(status_code=404, detail=f"File with id={file_id} not found.")
 
 
 async def load_file_to_source_async(server: SyncServer, source_id: str, job_id: str, filename: str, bytes: bytes, actor: User):

letta/server/rest_api/routers/v1/groups.py

@@ -1,17 +1,18 @@
 from typing import Annotated, List, Literal, Optional
 
-from fastapi import APIRouter, Body, Depends, Header, HTTPException, Query, status
+from fastapi import APIRouter, Body, Depends, Header, Query, status
 from fastapi.responses import JSONResponse
 from pydantic import Field
 
 from letta.constants import DEFAULT_MESSAGE_TOOL, DEFAULT_MESSAGE_TOOL_KWARG
-from letta.orm.errors import NoResultFound
-from letta.schemas.group import Group, GroupCreate, GroupUpdate, ManagerType
+from letta.schemas.group import Group, GroupBase, GroupCreate, GroupUpdate, ManagerType
 from letta.schemas.letta_message import LettaMessageUnion, LettaMessageUpdateUnion
 from letta.schemas.letta_request import LettaRequest, LettaStreamingRequest
 from letta.schemas.letta_response import LettaResponse
+from letta.schemas.message import BaseMessage
 from letta.server.rest_api.dependencies import HeaderParams, get_headers, get_letta_server
 from letta.server.server import SyncServer
+from letta.validators import GroupId, MessageId
 
 router = APIRouter(prefix="/groups", tags=["groups"])
 
@@ -69,7 +70,7 @@ async def count_groups(
 
 @router.get("/{group_id}", response_model=Group, operation_id="retrieve_group")
 async def retrieve_group(
-    group_id: str,
+    group_id: GroupId,
     server: "SyncServer" = Depends(get_letta_server),
     headers: HeaderParams = Depends(get_headers),
 ):
@@ -77,11 +78,7 @@ async def retrieve_group(
     Retrieve the group by id.
     """
     actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
-
-    try:
-        return await server.group_manager.retrieve_group_async(group_id=group_id, actor=actor)
-    except NoResultFound as e:
-        raise HTTPException(status_code=404, detail=str(e))
+    return await server.group_manager.retrieve_group_async(group_id=group_id, actor=actor)
 
 
 @router.post("/", response_model=Group, operation_id="create_group")
@@ -96,16 +93,13 @@ async def create_group(
     """
     Create a new multi-agent group with the specified configuration.
     """
-    try:
-        actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
-        return await server.group_manager.create_group_async(group, actor=actor)
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+    return await server.group_manager.create_group_async(group, actor=actor)
 
 
 @router.patch("/{group_id}", response_model=Group, operation_id="modify_group")
 async def modify_group(
-    group_id: str,
+    group_id: GroupId,
     group: GroupUpdate = Body(...),
     server: "SyncServer" = Depends(get_letta_server),
     headers: HeaderParams = Depends(get_headers),
@@ -116,16 +110,13 @@ async def modify_group(
     """
     Create a new multi-agent group with the specified configuration.
     """
-    try:
-        actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
-        return await server.group_manager.modify_group_async(group_id=group_id, group_update=group, actor=actor)
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+    return await server.group_manager.modify_group_async(group_id=group_id, group_update=group, actor=actor)
 
 
 @router.delete("/{group_id}", response_model=None, operation_id="delete_group")
 async def delete_group(
-    group_id: str,
+    group_id: GroupId,
     server: "SyncServer" = Depends(get_letta_server),
     headers: HeaderParams = Depends(get_headers),
 ):
@@ -133,11 +124,8 @@ async def delete_group(
     Delete a multi-agent group.
     """
     actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
-    try:
-        await server.group_manager.delete_group_async(group_id=group_id, actor=actor)
-        return JSONResponse(status_code=status.HTTP_200_OK, content={"message": f"Group id={group_id} successfully deleted"})
-    except NoResultFound:
-        raise HTTPException(status_code=404, detail=f"Group id={group_id} not found for user_id={actor.id}.")
+    await server.group_manager.delete_group_async(group_id=group_id, actor=actor)
+    return JSONResponse(status_code=status.HTTP_200_OK, content={"message": f"Group id={group_id} successfully deleted"})
 
 
 @router.post(
@@ -146,7 +134,7 @@ async def delete_group(
     operation_id="send_group_message",
 )
 async def send_group_message(
-    group_id: str,
+    group_id: GroupId,
     server: SyncServer = Depends(get_letta_server),
     request: LettaRequest = Body(...),
     headers: HeaderParams = Depends(get_headers),
@@ -184,7 +172,7 @@ async def send_group_message(
     },
 )
 async def send_group_message_streaming(
-    group_id: str,
+    group_id: GroupId,
     server: SyncServer = Depends(get_letta_server),
     request: LettaStreamingRequest = Body(...),
     headers: HeaderParams = Depends(get_headers),
@@ -216,8 +204,8 @@ GroupMessagesResponse = Annotated[
 
 @router.patch("/{group_id}/messages/{message_id}", response_model=LettaMessageUnion, operation_id="modify_group_message")
 async def modify_group_message(
-    group_id: str,
-    message_id: str,
+    group_id: GroupId,
+    message_id: MessageId,
     request: LettaMessageUpdateUnion = Body(...),
     server: "SyncServer" = Depends(get_letta_server),
     headers: HeaderParams = Depends(get_headers),
@@ -232,7 +220,7 @@ 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,
+    group_id: GroupId,
     before: Optional[str] = Query(
         None,
         description="Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order",
@@ -246,9 +234,9 @@ async def list_group_messages(
         "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."),
+    use_assistant_message: bool = Query(True, description="Whether to use assistant messages", deprecated=True),
+    assistant_message_tool_name: str = Query(DEFAULT_MESSAGE_TOOL, description="The name of the designated message tool.", deprecated=True),
+    assistant_message_tool_kwarg: str = Query(DEFAULT_MESSAGE_TOOL_KWARG, description="The name of the message argument.", deprecated=True),
     server: "SyncServer" = Depends(get_letta_server),
     headers: HeaderParams = Depends(get_headers),
 ):
@@ -287,7 +275,7 @@ async def list_group_messages(
 
 @router.patch("/{group_id}/reset-messages", response_model=None, operation_id="reset_group_messages")
 async def reset_group_messages(
-    group_id: str,
+    group_id: GroupId,
     server: "SyncServer" = Depends(get_letta_server),
     headers: HeaderParams = Depends(get_headers),
 ):

letta/server/rest_api/routers/v1/identities.py

@@ -1,12 +1,20 @@
-from typing import TYPE_CHECKING, List, Literal, Optional
+from typing import TYPE_CHECKING, List, Literal, Optional, Union
 
 from fastapi import APIRouter, Body, Depends, Header, Query
 
 from letta.orm.errors import NoResultFound, UniqueConstraintViolationError
-from letta.schemas.agent import AgentState
+from letta.schemas.agent import AgentRelationships, AgentState
 from letta.schemas.block import Block
-from letta.schemas.identity import Identity, IdentityCreate, IdentityProperty, IdentityType, IdentityUpdate, IdentityUpsert
+from letta.schemas.identity import (
+    Identity,
+    IdentityCreate,
+    IdentityProperty,
+    IdentityType,
+    IdentityUpdate,
+    IdentityUpsert,
+)
 from letta.server.rest_api.dependencies import HeaderParams, get_headers, get_letta_server
+from letta.validators import IdentityId
 
 if TYPE_CHECKING:
     from letta.server.server import SyncServer
@@ -41,7 +49,7 @@ async def list_identities(
     """
     actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
 
-    identities = await server.identity_manager.list_identities_async(
+    identities, next_cursor, has_more = await server.identity_manager.list_identities_async(
         name=name,
         project_id=project_id,
         identifier_key=identifier_key,
@@ -52,6 +60,7 @@ async def list_identities(
         ascending=(order == "asc"),
         actor=actor,
     )
+
     return identities
 
 
@@ -72,7 +81,7 @@ async def count_identities(
 
 @router.get("/{identity_id}", tags=["identities"], response_model=Identity, operation_id="retrieve_identity")
 async def retrieve_identity(
-    identity_id: str,
+    identity_id: IdentityId,
     server: "SyncServer" = Depends(get_letta_server),
     headers: HeaderParams = Depends(get_headers),
 ):
@@ -108,7 +117,7 @@ async def upsert_identity(
 
 @router.patch("/{identity_id}", tags=["identities"], response_model=Identity, operation_id="update_identity")
 async def modify_identity(
-    identity_id: str,
+    identity_id: IdentityId,
     identity: IdentityUpdate = Body(...),
     server: "SyncServer" = Depends(get_letta_server),
     headers: HeaderParams = Depends(get_headers),
@@ -119,7 +128,7 @@ async def modify_identity(
 
 @router.put("/{identity_id}/properties", tags=["identities"], operation_id="upsert_identity_properties")
 async def upsert_identity_properties(
-    identity_id: str,
+    identity_id: IdentityId,
     properties: List[IdentityProperty] = Body(...),
     server: "SyncServer" = Depends(get_letta_server),
     headers: HeaderParams = Depends(get_headers),
@@ -130,7 +139,7 @@ async def upsert_identity_properties(
 
 @router.delete("/{identity_id}", tags=["identities"], operation_id="delete_identity")
 async def delete_identity(
-    identity_id: str,
+    identity_id: IdentityId,
     server: "SyncServer" = Depends(get_letta_server),
     headers: HeaderParams = Depends(get_headers),
 ):
@@ -143,7 +152,7 @@ async def delete_identity(
 
 @router.get("/{identity_id}/agents", response_model=List[AgentState], operation_id="list_agents_for_identity")
 async def list_agents_for_identity(
-    identity_id: str,
+    identity_id: IdentityId,
     before: Optional[str] = Query(
         None,
         description="Agent ID cursor for pagination. Returns agents that come before this agent ID in the specified sort order",
@@ -157,6 +166,10 @@ async def list_agents_for_identity(
         "desc", description="Sort order for agents by creation time. 'asc' for oldest first, 'desc' for newest first"
     ),
     order_by: Literal["created_at"] = Query("created_at", description="Field to sort by"),
+    include: List[AgentRelationships] = Query(
+        [],
+        description=("Specify which relational fields to include in the response. No relationships are included by default."),
+    ),
     server: "SyncServer" = Depends(get_letta_server),
     headers: HeaderParams = Depends(get_headers),
 ):
@@ -170,13 +183,14 @@ async def list_agents_for_identity(
         after=after,
         limit=limit,
         ascending=(order == "asc"),
+        include=include,
         actor=actor,
     )
 
 
 @router.get("/{identity_id}/blocks", response_model=List[Block], operation_id="list_blocks_for_identity")
 async def list_blocks_for_identity(
-    identity_id: str,
+    identity_id: IdentityId,
     before: Optional[str] = Query(
         None,
         description="Block ID cursor for pagination. Returns blocks that come before this block ID in the specified sort order",

letta/server/rest_api/routers/v1/internal_runs.py

@@ -0,0 +1,107 @@
+from typing import List, Literal, Optional
+
+from fastapi import APIRouter, Depends, Query
+
+from letta.schemas.enums import ComparisonOperator, RunStatus
+from letta.schemas.letta_stop_reason import StopReasonType
+from letta.schemas.run import Run
+from letta.server.rest_api.dependencies import HeaderParams, get_headers, get_letta_server
+from letta.server.server import SyncServer
+from letta.services.run_manager import RunManager
+
+router = APIRouter(prefix="/_internal_runs", tags=["_internal_runs"])
+
+
+def convert_statuses_to_enum(statuses: Optional[List[str]]) -> Optional[List[RunStatus]]:
+    """Convert a list of status strings to RunStatus enum values.
+
+    Args:
+        statuses: List of status strings or None
+
+    Returns:
+        List of RunStatus enum values or None if input is None
+    """
+    if statuses is None:
+        return None
+    return [RunStatus(status) for status in statuses]
+
+
+@router.get("/", response_model=List[Run], operation_id="list_internal_runs")
+async def list_runs(
+    server: "SyncServer" = Depends(get_letta_server),
+    agent_id: Optional[str] = Query(None, description="The unique identifier of the agent associated with the run."),
+    agent_ids: Optional[List[str]] = Query(
+        None,
+        description="The unique identifiers of the agents associated with the run. Deprecated in favor of agent_id field.",
+        deprecated=True,
+    ),
+    statuses: Optional[List[str]] = Query(None, description="Filter runs by status. Can specify multiple statuses."),
+    background: Optional[bool] = Query(None, description="If True, filters for runs that were created in background mode."),
+    stop_reason: Optional[StopReasonType] = Query(None, description="Filter runs by stop reason."),
+    template_family: Optional[str] = Query(None, description="Filter runs by template family (base_template_id)."),
+    step_count: Optional[int] = Query(None, description="Filter runs by step count. Must be provided with step_count_operator."),
+    step_count_operator: ComparisonOperator = Query(
+        ComparisonOperator.EQ,
+        description="Operator for step_count filter: 'eq' for equals, 'gte' for greater than or equal, 'lte' for less than or equal.",
+    ),
+    tools_used: Optional[List[str]] = Query(None, description="Filter runs that used any of the specified tools."),
+    before: Optional[str] = Query(
+        None, description="Run ID cursor for pagination. Returns runs that come before this run ID in the specified sort order"
+    ),
+    after: Optional[str] = Query(
+        None, description="Run ID cursor for pagination. Returns runs that come after this run ID in the specified sort order"
+    ),
+    limit: Optional[int] = Query(100, description="Maximum number of runs to return"),
+    order: Literal["asc", "desc"] = Query(
+        "desc", description="Sort order for runs by creation time. 'asc' for oldest first, 'desc' for newest first"
+    ),
+    order_by: Literal["created_at"] = Query("created_at", description="Field to sort by"),
+    active: bool = Query(False, description="Filter for active runs."),
+    ascending: bool = Query(
+        False,
+        description="Whether to sort agents oldest to newest (True) or newest to oldest (False, default). Deprecated in favor of order field.",
+        deprecated=True,
+    ),
+    headers: HeaderParams = Depends(get_headers),
+):
+    """
+    List all runs.
+    """
+    actor = await server.user_manager.get_actor_or_default_async(actor_id=headers.actor_id)
+    runs_manager = server.run_manager
+
+    # Handle backwards compatibility: if statuses not provided but active=True, filter by active statuses
+    if statuses is None and active:
+        statuses = [RunStatus.created, RunStatus.running]
+
+    if agent_id:
+        # NOTE: we are deprecating agent_ids so this will the primary path soon
+        agent_ids = [agent_id]
+
+    # Handle backward compatibility: if ascending is explicitly set, use it; otherwise use order
+    if ascending is not False:
+        # ascending was explicitly set to True
+        sort_ascending = ascending
+    else:
+        # Use the new order parameter
+        sort_ascending = order == "asc"
+
+    # Convert string statuses to RunStatus enum
+    parsed_statuses = convert_statuses_to_enum(statuses)
+
+    runs = await runs_manager.list_runs(
+        actor=actor,
+        agent_ids=agent_ids,
+        statuses=parsed_statuses,
+        limit=limit,
+        before=before,
+        after=after,
+        ascending=sort_ascending,
+        stop_reason=stop_reason,
+        background=background,
+        template_family=template_family,
+        step_count=step_count,
+        step_count_operator=step_count_operator,
+        tools_used=tools_used,
+    )
+    return runs