Human in the Loop Automation: Awaiting Human and Resume in the Runs API
Most automation scripts assume smooth execution from start to finish. In reality, you often need a human to confirm a decision, handle an unexpected UI change, or approve a payment. The Runs API lets you pause an agent at any step by setting on_awaiting_human and then resume the run later with POST /v1/runs/{id}/resume. This keeps your workflows safe and controllable.
How awaiting_human works
When you create a run with POST /v1/runs, set on_awaiting_human to pause the agent when it hits the awaiting_human state rather than fail. The run transitions to awaiting_human and streams events via GET /v1/runs/{id}/events. You can inspect those events to see the current UI and decide how to proceed. To continue, send POST /v1/runs/{id}/resume with an optional instructions field to append to the base prompt. The run resumes from the last successful step.
#!/usr/bin/env bash
set -e
COASTY_API_KEY="${COASTY_API_KEY:-}"
if [[ -z "$COASTY_API_KEY" ]]; then
echo "Error: COASTY_API_KEY environment variable is not set" >&2
exit 1
fi
# Create a run that will pause for human approval
curl -s -X POST https://coasty.ai/v1/runs \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "machine-abc123",
"task": "Open Chrome, navigate to https://coasty.ai, and select the pricing link",
"cua_version": "v4",
"on_awaiting_human": "pause",
"deadline_seconds": 600
}' | jq '.'
RUN_ID=$(curl -s -X POST https://coasty.ai/v1/runs \
-H "X-API-Key: $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "machine-abc123",
"task": "Open Chrome, navigate to https://coasty.ai, and select the pricing link",
"cua_version": "v4",
"on_awaiting_human": "pause",
"deadline_seconds": 600
}' | jq -r '.id')
echo "Run created with id: $RUN_ID"
echo "Waiting for run to reach awaiting_human 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 '.status')
echo "Current status: $STATUS"
if [[ "$STATUS" == "awaiting_human" ]]; then
echo "Run is paused, awaiting human approval. Inspect events via GET /v1/runs/$RUN_ID/events"
break
fi
sleep 2
done
echo "Resuming run with additional instructions..."
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 '{
"instructions": "After pausing, click the Continue button and complete the task."
}' | jq '.'Key fields and behaviors
- ●POST /v1/runs requires machine_id, task, and cua_version. Pass on_awaiting_human as one of pause, fail, or cancel to control behavior when the run reaches awaiting_human. Default is fail if not specified.
- ●The run status can be queued, running, awaiting_human, succeeded, failed, cancelled, or timed_out. Check status via GET /v1/runs/{id} to decide when to resume.
- ●GET /v1/runs/{id}/events streams Server-Sent Events. Reconnect using the Last-Event-ID header if you disconnect. Events show progress and the current state including awaiting_human.
- ●POST /v1/runs/{id}/resume accepts an optional instructions JSON string that gets appended to the base prompt for the next prediction step.
- ●Billing is $0.05 per agent step. Paused runs still consume credits when they are in the running or awaiting_human states, not while idle.
Set on_awaiting_human: "pause", then use POST /v1/runs/{id}/resume with instructions to continue.
Where this beats brittle automation
Traditional automation relies on brittle selectors like XPath or CSS classes that break when a UI changes. The Runs API uses a computer use agent that sees the screen, reads text and images, and acts like a human. When the agent encounters an ambiguous or risky action, you can pause it and review the screenshot and context. This makes your workflows adaptable to real-world UI changes without rewriting selectors. You can inspect events to see exactly what the agent sees, then give it the right guidance to proceed.
Use awaiting_human and resume to build automation that can pause safely and continue with human input. Combine this with workflows for complex, multi-step pipelines that gate on approvals. Start building with a free key at https://coasty.ai/developers.