Human in the Loop Automation: Awaiting Human and Resume in the Runs API
Fully autonomous agents can hit edge cases or unexpected UI changes. Instead of failing and restarting, you want a run to pause, ask a human for clarification, and resume later. The runs API gives you this flow with the awaiting_human state and resume endpoint.
How awaiting_human and resume work
When a run hits a scenario requiring human input, the server transitions its state to awaiting_human. The GET /v1/runs/{id}/events endpoint streams a Server-Sent Event marking the state change. You fetch the latest event, present the situation to a human, and call POST /v1/runs/{id}/resume with the human's response. The run continues from the last successful step.
#!/usr/bin/env bash
COASTY_API_KEY=$COASTY_API_KEY
RUN_ID="run_abc123"
# Start a run that can await human input
START_RESPONSE=$(curl -s -X POST https://coasty.ai/v1/runs \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "mch_123",
"task": "Navigate to https://example.com and click the Contact Us link",
"cua_version": "v3",
"on_awaiting_human": "pause"
}')
RUN_ID=$(echo $START_RESPONSE | jq -r '.id')
echo "Started run $RUN_ID"
# Stream events to detect awaiting_human
while true; do
EVENTS=$(curl -s -N -H "X-API-Key: $COASTY_API_KEY" \
"https://coasty.ai/v1/runs/$RUN_ID/events")
STATE=$(echo "$EVENTS" | jq -r '.state // empty' | tail -1)
if [[ "$STATE" == "awaiting_human" ]]; then
echo "Run is awaiting human input. Present the last event to a human."
# In production, present the event payload to the human and collect a choice
HUMAN_CHOICE="continue"
curl -s -X POST https://coasty.ai/v1/runs/$RUN_ID/resume \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"response": "'$HUMAN_CHOICE'"
}' | jq -r '.state'
break
fi
if [[ "$STATE" == "succeeded" || "$STATE" == "failed" || "$STATE" == "cancelled" ]]; then
echo "Run ended with state: $STATE"
break
fi
sleep 2
done
Use on_awaiting_human to control behavior
- ●Set on_awaiting_human to "pause" to let the server transition to awaiting_human and stream the event.
- ●Set on_awaiting_human to "fail" to treat a human request as a failure and end the run.
- ●Set on_awaiting_human to "cancel" to stop the run at the point of request.
- ●The run states include queued, running, awaiting_human, succeeded, failed, cancelled, and timed_out.
Resume with a human decision
- ●Call POST /v1/runs/{id}/resume with a JSON body containing a response field.
- ●The server uses your response to continue the trajectory from the last checkpoint.
- ●Resuming respects max_steps and deadline_seconds if they were set on the original run.
- ●Each task step continues to be billed $0.05 per agent step.
Set on_awaiting_human: "pause" and stream events to detect awaiting_human, then POST /v1/runs/{id}/resume to let the agent continue.
Where this beats brittle automation
Traditional automation relies on brittle selectors, hardcoded IDs, or fragile API mocks. When UI changes, the script fails and you rebuild logic. With a computer use agent, the agent sees the actual screen, understands layout, and can ask for clarification when it encounters ambiguity. Human in the loop lets you handle edge cases, consent screens, or multi-step approvals without rewriting your script.
Use awaiting_human and resume to build reliable, interactive automation. Create workflows that pause for review, resume after human input, and keep costs predictable. Get your API key at https://coasty.ai/developers and start building computer use agents that work like real users.