OpenHands / OpenHands/enterprise
Add execution_status query filter to /api/v1/app-conversations/search endpoint
Nobody has claimed this yet.
- 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__containscreated_at__gte/created_at__ltupdated_at__gte/updated_at__ltsandbox_id__eq
But does NOT support:
execution_status__eqorstatusquery 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 (
__eqpattern)
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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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