Human in the Loop Automation: awaiting_human and resume in the runs API
API-only automation often breaks when UI changes or a step needs judgment. With the runs API, your agent can enter an awaiting_human state instead of failing. You review, approve, or cancel, then resume the run. This gives you reliable computer use agents that work on real desktops, browsers, and terminals without brittle selectors.
How awaiting_human works
When you start a task run, the server drives the agent step by step. If the agent hits a situation that requires human input, it transitions to the awaiting_human state. The server streams events via GET /v1/runs/{id}/events. Each event includes the current state. You inspect the event payload, prompt a human, and decide how to proceed. The run stays alive in memory, preserving all previous trajectory. You can cancel, pause, or resume it. The next request to POST /v1/sessions/{id}/predict or a new step from the runs API continues from the same point.
1. Start a run with awaiting_human enabled
export COASTY_API_KEY=$COASTY_API_KEY
curl -X POST https://coasty.ai/v1/runs \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "machine-123",
"task": "Open a browser and navigate to https://example.com",
"cua_version": "v3",
"on_awaiting_human": "pause"
}'
2. Stream events to detect the awaiting_human state
curl -N https://coasty.ai/v1/runs/$RUN_ID/events \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Accept: text/event-stream"
3. Review events, then resume when ready
curl -X POST https://coasty.ai/v1/runs/$RUN_ID/resume \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"instructions": "Confirm navigation and proceed to the next step."
}'on_awaiting_human options
- ●"pause" keeps the run in awaiting_human and streams events until you resume or cancel.
- ●"fail" transitions the run to failed with an error, preserving the state for debugging.
- ●"cancel" immediately cancels the run and returns a cancelled state.
Resume with instructions
POST /v1/runs/{id}/resume accepts an optional instructions field. You can append guidance for the next step or override the original task. This is useful for feedback loops. The agent continues from the last successful action and respects the same cua_version and machine context.
Use on_awaiting_human to pause runs and resume with instructions for reliable human-in-the-loop automation.
Where this beats brittle automation
Traditional automation relies on hardcoded selectors, XPath, or element IDs. When a UI changes, the script breaks. With computer use, the agent sees the screen, interprets text and layout, and navigates naturally. Awaiting_human lets you intervene at the right moment without stopping the whole pipeline. This works across browsers, desktop apps, and terminals. You get stateful trajectory memory, so the agent doesn’t forget where it left off after a pause.
Add human approval to your computer use agent. Start a run with on_awaiting_human set to pause, watch events, resume with instructions when ready. Get your API key at https://coasty.ai/developers and build resilient automation today.