Human in the Loop Automation: Awaiting Human and Resume in the Runs API
Automated agents can do a lot, but some tasks need a human decision. You might need approval for a purchase, confirmation of a file move, or review of a generated report. The runs API lets you pause an agent when it hits a human step and resume from the same state when the human approves. This post shows how to use awaiting_human and resume with POST /v1/runs, GET /v1/runs, and POST /v1/runs/{id}/resume. No brittle selectors needed.
How awaiting_human and resume work
When you start a run with POST /v1/runs, you can set on_awaiting_human to "pause". The agent still drives the desktop, but the run state becomes "awaiting_human" instead of "running". The endpoint returns the run ID. You poll GET /v1/runs or GET /v1/runs/{id} to check the state. When the human approves, call POST /v1/runs/{id}/resume. The server continues from the last action, using the same trajectory memory. The run state becomes "running" again until it reaches success, failure, or another human step.
Create a run that pauses on human approval.
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": "Create a file named approval.txt and stop",
"cua_version": "v4",
"on_awaiting_human": "pause",
"max_steps": 20
}'
# Response:
# {
# "id": "run-abc123",
# "state": "running",
# ...
# }Run states and transitions
- ●queued: The run is queued for execution.
- ●running: The agent is driving the desktop. Billed $0.05 per agent step.
- ●awaiting_human: The run paused because of a human_approval step. Use POST /v1/runs/{id}/resume to continue.
- ●succeeded: All steps completed successfully.
- ●failed: A step failed, either due to the agent or a guard.
- ●cancelled: You canceled the run with POST /v1/runs/{id}/cancel.
- ●timed_out: The deadline_seconds limit was exceeded.
Set on_awaiting_human to "pause" when you want a human step, then call POST /v1/runs/{id}/resume to continue.
Where this beats brittle automation
API-only tools often rely on hard selectors, IDs, and paths that break when UIs change. The computer use agent sees the screen, clicks, and types like a human. When the agent reaches a human_approval step, it pauses safely. You approve from your dashboard or webhook, and the agent resumes from the exact last action. This avoids flaky selectors and lets you build robust workflows that stay in sync with the real user interface.
Use awaiting_human and resume to build safer automation with the runs API. Set on_awaiting_human to pause, poll the run state, and resume with POST /v1/runs/{id}/resume. Combine this with workflows and task runs for complex, multi-step automation. Get a key at https://coasty.ai/developers and try it in your next project.