Human in the Loop Automation: Awaiting Human and Resume in the Runs API
Traditional bots either fail when they hit a form you need to sign or run blindly and make mistakes. The Coasty computer use API lets you pause at a human gate, resume when you are ready, and keep the agent running autonomously. This feature relies on the awaiting_human state in POST /v1/runs and the resume endpoint to continue from where the agent left off.
How awaiting_human and resume work
When you submit a task via POST /v1/runs, the server drives the computer use agent step by step. If the agent encounters a UI element that needs approval, it transitions to the awaiting_human state. You can poll GET /v1/runs/{id} to detect this state. Once you are ready, a POST to /v1/runs/{id}/resume moves the task back to queued or running. The agent then continues executing until success, failure, or another human approval point.
#!/bin/bash
set -e
COASTY_API_KEY="$COASTY_API_KEY"
# Start a task that may pause for approval
RUN_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": "cloud-vm-123",
"task": "Fill out annual tax form and submit",
"cua_version": "v4",
"max_steps": 100,
"on_awaiting_human": "pause"
}')
RUN_ID=$(echo "$RUN_RESPONSE" | jq -r '.run.id')
echo "Task started: $RUN_ID"
# Poll for state changes until we hit awaiting_human
while true; do
STATUS=$(curl -s -X GET "https://coasty.ai/v1/runs/$RUN_ID" \
-H "X-API-Key: $COASTY_API_KEY" | jq -r '.run.state')
echo "Current state: $STATUS"
if [[ "$STATUS" == "awaiting_human" ]]; then
echo "Agent paused for approval. Complete the human step, then resume."
break
fi
if [[ "$STATUS" == "succeeded" || "$STATUS" == "failed" ]]; then
echo "Task finished: $STATUS"
exit 0
fi
sleep 2
done
# Resume the task when you are ready
RESUME_RESPONSE=$(curl -s -X POST "https://coasty.ai/v1/runs/$RUN_ID/resume" \
-H "X-API-Key: $COASTY_API_KEY")
echo "Resume response: $RESUME_RESPONSE"
# Continue polling until final state
while true; do
STATUS=$(curl -s -X GET "https://coasty.ai/v1/runs/$RUN_ID" \
-H "X-API-Key: $COASTY_API_KEY" | jq -r '.run.state')
echo "New state: $STATUS"
if [[ "$STATUS" == "succeeded" || "$STATUS" == "failed" || "$STATUS" == "cancelled" ]]; then
echo "Task finished: $STATUS"
exit 0
fi
sleep 2
doneKey parameters and state transitions
- ●on_awaiting_human can be pause, fail, or cancel. Set it to pause to keep the run alive while you act.
- ●States include queued, running, awaiting_human, succeeded, failed, cancelled, timed_out.
- ●POST /v1/runs/{id}/resume accepts no body but restarts execution from the last checkpoint.
- ●You pay $0.05 per agent step regardless of pause duration. The resume does not incur extra cost.
- ●You can stream events via GET /v1/runs/{id}/events with Last-Event-ID for reconnection.
Set on_awaiting_human to pause and poll GET /v1/runs/{id} to detect awaiting_human, then POST /v1/runs/{id}/resume to continue.
Where awaiting_human beats brittle automation
Static selectors and fixed API calls break when a UI changes, an app requires multi-factor approval, or a regulatory form needs a human signature. A computer use agent can see the screen, understand context, and hand off to you at the right moment. The awaiting_human state keeps the session alive so you can complete the step and resume smoothly without restarting the entire workflow.
Use awaiting_human and resume to build approvals, tax workflows, or account unlocks that stay reliable across UI changes. Start building at https://coasty.ai/developers to get your API key and try the runs API today.