OpenHands / OpenHands/enterprise

Add execution_status query filter to /api/v1/app-conversations/search endpoint

Open
#65 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Python
Stars
4
Forks
2
Avg merge
1d 22h
Merged PRs (30d)
101

Description

Problem

The V1 conversation search endpoint does not support filtering by execution status, requiring clients to fetch all conversations and filter client-side. This is inefficient for users with many conversations.

Current Behavior

GET /api/v1/app-conversations/search supports:

  • title__contains
  • created_at__gte / created_at__lt
  • updated_at__gte / updated_at__lt
  • sandbox_id__eq

But does NOT support:

  • execution_status__eq or status query parameter
Current Workaround

Clients must fetch all conversations and filter client-side:

response = get("/api/v1/app-conversations/search?limit=100")
running = [c for c in response["items"] 
           if c["execution_status"] == "RUNNING"]

This requires:

  • Fetching all pages of results
  • Transferring unnecessary data over the network
  • Filtering on the client side

Proposed Solution

Add query parameters to /api/v1/app-conversations/search:

  • execution_status__eq - Filter by execution status (e.g., RUNNING, STOPPED, ERROR)
  • sandbox_status__eq - Filter by sandbox status (e.g., RUNNING, PAUSED, STOPPED)
Example Usage
GET /api/v1/app-conversations/search?execution_status__eq=RUNNING&limit=100

Impact

Severity: Low

  • Workaround exists (client-side filtering)
  • Performance impact minimal for small/medium conversation counts
  • Becomes problematic only with hundreds/thousands of conversations

Benefit:

  • Improved performance for large conversation lists
  • Reduced network traffic
  • More efficient queries
  • Consistency with other filter parameters (__eq pattern)

Use Case

Users managing multiple long-running conversations need to query only active ones without fetching the entire conversation list. This is particularly important for:

  • Monitoring dashboards showing only running conversations
  • Cleanup scripts targeting stopped conversations
  • Status-based pagination in UIs

Related

Legacy V0 API (/api/conversations) supported status filtering, which will be removed on 2026-04-01. This feature would provide equivalent functionality in the V1 API.


This issue was filed by an AI agent (OpenHands) on behalf of the user.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the implementation and tests for GET /api/v1/app-conversations/search, then trace how existing query filters such as title__contains and sandbox_id__eq are defined and applied. Add coverage for execution_status__eq and sandbox_status__eq, including the RUNNING example; done means matching conversations are returned without client-side filtering and existing filters still work.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, backend
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.