Human in the Loop Automation: Awaiting Human and Resume in the Runs API
Most automation scripts assume they can finish a task without human help. That assumption breaks when a screen needs a password, a policy popup appears, or a checkout asks for ID verification. Instead of writing brittle heuristics to handle every edge case, you can let the agent pause and hand control back to a human. The runs endpoint supports this with on_awaiting_human and resume. You send a run, set on_awaiting_human to pause, and when the server reports the run is awaiting_human you pause your own logic, let a human review the current state, and call resume to continue from the last step.
How awaiting_human and resume work
Create a run with the POST /v1/runs endpoint. Include on_awaiting_human with a value of pause. The server starts the agent and watches for situations requiring human approval. The agent uses computer vision to interpret the screen, then generates actions like clicks, typing, and scrolling. When the agent detects a human-only state it stops and transitions the run to the awaiting_human state. To continue, call POST /v1/runs/{id}/resume. The server resumes from the last successful step, not from the beginning, so you do not repeat already completed work. The run remains in the running state until it finishes, fails, times out, or is cancelled. You can also GET /v1/runs/{id}/events to stream the sequence of steps with timestamps.
curl -X POST https://coasty.ai/v1/runs \
-H "Authorization: Bearer $COASTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"machine_id": "m-abc123",
"task": "Open Chrome, navigate to https://example.com, and fill in the search box with "test" and click search",
"cua_version": "v4",
"max_steps": 100,
"deadline_seconds": 600,
"on_awaiting_human": "pause",
"webhook_url": "https://your-server.com/runs/webhook"
}'Run lifecycle and states
- ●queued: the run is accepted and placed in a processing queue
- ●running: the agent is executing steps, including those that trigger awaiting_human
- ●awaiting_human: the agent has paused and waited for a resume call
- ●succeeded: all steps completed without failure
- ●failed: one or more steps failed, and the run stopped
- ●cancelled: you called POST /v1/runs/{id}/cancel
- ●timed_out: the run exceeded deadline_seconds
Resume and cancellation patterns
After a run reaches awaiting_human, do not send another /v1/runs/{id}/predict call. Instead, call POST /v1/runs/{id}/resume. This API tells the server the human has reviewed and approved the current state. If you want to stop the run before it finishes, send POST /v1/runs/{id}/cancel. The server will transition the run to the cancelled state and stop executing steps. You can fetch the final state with GET /v1/runs/{id} and inspect the events stream to see exactly where the run paused. This pattern lets you build approval gates for sensitive actions, such as deleting files or making purchases.
Set on_awaiting_human to pause, wait for the run to enter awaiting_human, then call POST /v1/runs/{id}/resume to continue.
Where this beats brittle automation
Traditional automation relies on declarative selectors like CSS classes, IDs, or XPath. Those selectors break when a UI changes, when a screen is rendered differently, or when a popup appears. Computer use agents see the screen exactly as a human does. They can recognize a captcha, a consent dialog, or a dynamic element by appearance. By pausing at natural human checkpoints and resuming after approval, you avoid writing fragile heuristics for every edge case. You can also integrate with your own approval systems through webhooks, so a human approves only after reviewing logs and screenshots.
You can now build workflows that pause for human input instead of failing or guessing. Create runs with on_awaiting_human: pause, monitor the events stream, resume with POST /v1/runs/{id}/resume, and cancel when needed. This approach keeps your automation robust and aligned with real-world workflows. Get your API key at https://coasty.ai/developers and start building human-in-the-loop computer use agents.