Human in the Loop Automation: Awaiting Human and Resume in the Runs API
Most automation scripts fail when they hit an unexpected UI or a condition they cannot resolve. The runs API gives you a way to drive a computer use agent through a real desktop, but sometimes you need a human to make a judgment call. By setting on_awaiting_human to pause, the agent stops in a known state and you can review the situation, approve, or cancel. After that, you resume the run from the same trajectory, continuing exactly where it left off.
How awaiting_human and resume work
When you POST /v1/runs with on_awaiting_human set to pause, the agent runs until it needs human interaction. The run enters the awaiting_human state. You can poll GET /v1/runs/{id} to see the current state, or stream events from GET /v1/runs/{id}/events. Once you decide, you call POST /v1/runs/{id}/resume. The request body can include optional instructions that get appended to the base prompt. The agent continues from its latest trajectory memory, using the same cua_version (v3 or v4). The entire flow is billed at $0.05 per agent step.
#!/bin/bash
# POST a task that may require human approval
COASTY_API_KEY="${COASTY_API_KEY}"
# start a run with on_awaiting_human = pause
RUN_RESPONSE=$(curl -s -X POST https://coasty.ai/v1/runs \
-H "Authorization: Bearer $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "prod-01",
"task": "Open the admin settings page and click save if the form is valid, otherwise ask for human approval",
"cua_version": "v4",
"on_awaiting_human": "pause",
"max_steps": 20,
"deadline_seconds": 300
}')
RUN_ID=$(echo $RUN_RESPONSE | jq -r '.id')
echo "Run $RUN_ID created"
# poll until the run hits awaiting_human
while true; do
STATUS=$(curl -s -X GET https://coasty.ai/v1/runs/$RUN_ID \
-H "Authorization: Bearer $COASTY_API_KEY" | jq -r '.status')
echo "Status: $STATUS"
if [[ $STATUS == "awaiting_human" ]]; then
echo "Agent paused. Review events then resume."
break
elif [[ $STATUS == "succeeded" ]] || [[ $STATUS == "failed" ]]; then
echo "Run ended with $STATUS"
exit 0
fi
sleep 2
done
# resume from the same state
RESUME_RESPONSE=$(curl -s -X POST https://coasty.ai/v1/runs/$RUN_ID/resume \
-H "Authorization: Bearer $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"instructions": "After human approval, continue by clicking confirm and closing the dialog."
}')
echo "Resume response: $RESUME_RESPONSE"Key fields and options
- ●POST /v1/runs sets the run. Use on_awaiting_human: pause, fail, or cancel to decide how the agent behaves when it needs a human.
- ●GET /v1/runs/{id} returns the status, which can be queued, running, awaiting_human, succeeded, failed, cancelled, or timed_out.
- ●GET /v1/runs/{id}/events streams Server-Sent Events and can reconnect with Last-Event-ID for long-running tasks.
- ●POST /v1/runs/{id}/resume accepts an optional instructions field that gets appended to the base prompt, letting you give fresh guidance without resetting the state.
- ●Task steps are billed at $0.05 each. The entire workflow is stateful, so every agent step uses trajectory memory from POST /v1/sessions.
- ●The cua_version defaults to v3; v4 adds a pass/fail verifier and can make autonomous decisions after human approval.
Set on_awaiting_human to pause, then resume from the same run ID with fresh instructions to keep the automation human-in-the-loop.
Where this beats brittle automation
Traditional automation relies on brittle selectors like XPath or CSS that break when UI changes. A computer use agent sees the screen, reads text, and clicks visually similar elements, so it adapts to layout changes. By pausing on uncertain conditions and resuming after a human decision, you get the reliability of explicit logic combined with the flexibility of screen-based control. You don't need to guess every edge case in advance.
Combine screen-based judgment with programmatic flow by using awaiting_human and resume in the runs API. Build workflows that pause for approval, handle edge cases, and rejoin the automated path. Get a key and start building at https://coasty.ai/developers.