From ea34fdeeb737924d77c186d2c2f06764744afb9f Mon Sep 17 00:00:00 2001
From: cthomas <caren@letta.com>
Date: Tue, 26 Aug 2025 10:52:36 -0700
Subject: [PATCH] feat: add background filter to list runs endpoint (#4196)

---
 letta/server/rest_api/routers/v1/agents.py |  1 +
 letta/server/rest_api/routers/v1/runs.py   | 20 +++++++++++++++-----
 2 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/letta/server/rest_api/routers/v1/agents.py b/letta/server/rest_api/routers/v1/agents.py
index b1a97f9e..084f2345 100644
--- a/letta/server/rest_api/routers/v1/agents.py
+++ b/letta/server/rest_api/routers/v1/agents.py
@@ -1206,6 +1206,7 @@ async def send_message_streaming(
                 metadata={
                     "job_type": "send_message_streaming",
                     "agent_id": agent_id,
+                    "background": request.background or False,
                 },
                 request_config=LettaRequestConfig(
                     use_assistant_message=request.use_assistant_message,
diff --git a/letta/server/rest_api/routers/v1/runs.py b/letta/server/rest_api/routers/v1/runs.py
index d9dcf84a..2d0085e4 100644
--- a/letta/server/rest_api/routers/v1/runs.py
+++ b/letta/server/rest_api/routers/v1/runs.py
@@ -24,6 +24,7 @@ router = APIRouter(prefix="/runs", tags=["runs"])
 def list_runs(
     server: "SyncServer" = Depends(get_letta_server),
     agent_ids: Optional[List[str]] = Query(None, description="The unique identifier of the agent associated with the run."),
+    background: Optional[bool] = Query(False, description="If True, filters for runs that were created in background mode."),
     actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
 ):
     """
@@ -33,16 +34,20 @@ def list_runs(
 
     runs = [Run.from_job(job) for job in server.job_manager.list_jobs(actor=actor, job_type=JobType.RUN)]
 
-    if not agent_ids:
-        return runs
+    if agent_ids:
+        runs = [run for run in runs if "agent_id" in run.metadata and run.metadata["agent_id"] in agent_ids]
 
-    return [run for run in runs if "agent_id" in run.metadata and run.metadata["agent_id"] in agent_ids]
+    if background:
+        runs = [run for run in runs if "background" in run.metadata and run.metadata["background"]]
+
+    return runs
 
 
 @router.get("/active", response_model=List[Run], operation_id="list_active_runs")
 def list_active_runs(
     server: "SyncServer" = Depends(get_letta_server),
     agent_ids: Optional[List[str]] = Query(None, description="The unique identifier of the agent associated with the run."),
+    background: Optional[bool] = Query(False, description="If True, filters for runs that were created in background mode."),
     actor_id: Optional[str] = Header(None, alias="user_id"),  # Extract user_id from header, default to None if not present
 ):
     """
@@ -55,9 +60,14 @@ def list_active_runs(
     active_runs = [Run.from_job(job) for job in active_runs]
 
     if not agent_ids:
-        return active_runs
+        runs = active_runs
+    else:
+        runs = [run for run in active_runs if "agent_id" in run.metadata and run.metadata["agent_id"] in agent_ids]
 
-    return [run for run in active_runs if "agent_id" in run.metadata and run.metadata["agent_id"] in agent_ids]
+    if background:
+        runs = [run for run in runs if "background" in run.metadata and run.metadata["background"]]
+
+    return runs
 
 
 @router.get("/{run_id}", response_model=Run, operation_id="retrieve_run")