docs: Add conversation status checking documentation for Cloud API#365
docs: Add conversation status checking documentation for Cloud API#365
Conversation
Add documentation explaining how to check the status of conversations started via the V1 API: - Step 1: Poll start-tasks endpoint until status is READY - Step 2: Use app_conversation_id to check execution_status - Document sandbox_status and execution_status field values - Include complete polling example in Python This addresses the gap where users could start conversations but had no documented way to programmatically check if the agent completed. Closes #364 Co-authored-by: openhands <openhands@all-hands.dev>
The search endpoint has a known issue (OpenHands/OpenHands#13121). Recommend using batch_get by ID when the conversation ID is known. Co-authored-by: openhands <openhands@all-hands.dev>
Documents the search endpoint with correct response format: - Returns 'items' array (not 'results') - Shows pagination with next_page_id Co-authored-by: openhands <openhands@all-hands.dev>
The search endpoint works correctly - my earlier testing had a bug where I was checking for 'results' instead of 'items'. Co-authored-by: openhands <openhands@all-hands.dev>
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
Taste Rating: 🟡 Acceptable - Solves a real problem with clear documentation.
Main Issue: The polling examples have infinite loops without timeouts. Users who copy-paste this code will have processes that hang forever if the API misbehaves.
- Add max_attempts counter to start task polling loop (5 min timeout) - Add max_attempts counter to conversation polling loop (1 hour timeout) - Handle timeout cases with appropriate error messages Co-authored-by: openhands <openhands@all-hands.dev>
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
Taste Rating: 🟡 Acceptable - Solves a real problem with clear documentation.
Main Issue: The polling examples have error handling gaps that will confuse users who copy-paste this code. When the API returns errors or unexpected data, the examples will throw exceptions instead of failing gracefully.
- Add Note warning about production error handling at start of section - Add raise_for_status() for HTTP error handling in all examples - Use safe list access with len() checks to prevent IndexError - Improve status documentation with actions for each state - Add terminal states Note explaining which states exit polling loops - Handle waiting_for_confirmation state in Complete Polling Example - Handle ERROR status in start task polling loop Co-authored-by: openhands <openhands@all-hands.dev>
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
Taste Rating: 🟡 Acceptable - Solves a real problem with clear documentation.
Critical Issue: The polling loop ignores sandbox_status, so if the sandbox crashes (ERROR/MISSING), your code will poll for an hour instead of failing immediately. You document these terminal states but don't check them.
Key Insight: Example code teaches patterns - make them fail fast when infrastructure dies, not just when tasks fail.
- Use pythonic conditionals (remove redundant len() checks) - Show API error details instead of vague message - Check sandbox_status for ERROR/MISSING states before exec_status - Add exit(1) on timeout failure - Remove redundant conversations length check Co-authored-by: openhands <openhands@all-hands.dev>
all-hands-bot
left a comment
all-hands-bot
left a comment
There was a problem hiding this comment.
Taste Rating: 🟡 Acceptable - Solves a real problem with clear documentation.
Main Issue: Minor inconsistencies between examples could confuse users about the recommended coding pattern.
- Use pythonic conditional in Step 2 example (remove redundant len()) - Add raise_for_status() to Listing example for consistency Co-authored-by: openhands <openhands@all-hands.dev>
Added the SETTING_UP_SKILLS status which was discovered during API testing. This status appears when the agent is configuring skills and tools after the sandbox is ready but before the conversation is fully ready. Co-authored-by: openhands <openhands@all-hands.dev>
4 participants
Summary
Add documentation explaining how to check the status of conversations started via the V1 Cloud API.
Changes
Added a new "Checking Conversation Status" section to the Cloud API documentation that covers:
Step 1: Check Start Task Status - Poll the
/api/v1/app-conversations/start-tasksendpoint until the status becomesREADYandapp_conversation_idis availableStep 2: Check Conversation Execution Status - Use the
app_conversation_idto query/api/v1/app-conversationsand checksandbox_statusandexecution_statusStatus Fields Documentation - Documented all possible values for:
sandbox_status: STARTING, RUNNING, PAUSED, ERROR, MISSINGexecution_status: idle, running, paused, waiting_for_confirmation, finished, error, stuckComplete Polling Example - Added a full Python example showing how to start a conversation and poll until the agent completes
Why This Is Needed
The existing documentation showed how to start conversations but didn't explain how to programmatically check if the agent completed its task. This is essential for automation use cases where users need to:
Testing
I verified these endpoints work correctly:
GET /api/v1/app-conversations/start-tasks?ids=TASK_ID✅GET /api/v1/app-conversations?ids=CONVERSATION_ID✅Closes #364